Help us shape the future of Go! Take the 2026 Go Developer Survey

sgfilter

package
v1.9.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 27, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package sgfilter evaluates EC2 security-group rules against network flows and fronts container-published ports with a TCP proxy that admits or refuses clients by those rules. Enforcement is opt-in: a nil *Enforcer admits everything.

Index

Constants

View Source
const (
	ProtoTCP  = "tcp"
	ProtoUDP  = "udp"
	ProtoICMP = "icmp"
)

Protocol names used by flows.

View Source
const DialTimeout = 10 * time.Second

DialTimeout bounds each upstream dial.

View Source
const ProtoAll = "-1"

ProtoAll is the security-group protocol that matches every IP protocol and ignores ports.

Variables

This section is empty.

Functions

func AddrOf

func AddrOf(a net.Addr) netip.Addr

AddrOf extracts the IP of a remote address; the zero Addr when it has none.

func AllowEgress

func AllowEgress(groups []Group, f Flow) bool

AllowEgress reports whether any group's egress rule admits the flow; with no matching rule it is denied.

func AllowIngress

func AllowIngress(groups []Group, f Flow) bool

AllowIngress reports whether any group admits the flow; with no groups, or no matching rule, it is denied.

func Guard

func Guard(ln net.Listener, admit Admitter) net.Listener

Guard wraps ln so Accept drops clients admit rejects; a nil admit returns ln unchanged.

func NormalizeProtocol

func NormalizeProtocol(p string) string

NormalizeProtocol maps protocol numbers and mixed-case names onto "tcp", "udp" and "icmp"; "-1" and unknown values pass through lower-cased.

func Pipe

func Pipe(client, up net.Conn)

Pipe copies both directions until either side closes.

Types

type Admitter

type Admitter func(remote net.Addr) bool

Admitter decides whether a remote client may connect.

type DefaultGroupSource

type DefaultGroupSource interface {
	// DefaultGroupID returns the default group of vpcID; an empty vpcID means the default VPC.
	DefaultGroupID(vpcID string) string
}

DefaultGroupSource is optionally implemented by a Source that knows each VPC's default security group, which AWS attaches to resources created without one.

type Dialer

type Dialer interface {
	DialContext(ctx context.Context, network, address string) (net.Conn, error)
}

Dialer opens upstream connections; *net.Dialer satisfies it and tests inject a fake.

type Enforcer

type Enforcer struct {
	// contains filtered or unexported fields
}

Enforcer evaluates flows against the groups its Source reports. A nil Enforcer admits everything, so services hold one unconditionally and the operator flag decides whether it is set.

func New

func New() *Enforcer

New returns an Enforcer with no Source; until SetSource, every group is empty and ingress is denied.

func (*Enforcer) AdmitIngress

func (e *Enforcer) AdmitIngress(sgIDs []string, proto string, port int, remote net.Addr) bool

AdmitIngress reports whether a client at remote may open proto/port on a target carrying sgIDs.

func (*Enforcer) AdmitIngressInVPC

func (e *Enforcer) AdmitIngressInVPC(vpcID string, sgIDs []string, proto string, port int, remote net.Addr) bool

AdmitIngressInVPC is AdmitIngress for a target in vpcID; with no sgIDs the VPC's default group applies, as AWS does for a resource created without one. An empty vpcID means the default VPC.

func (*Enforcer) Ingress

func (e *Enforcer) Ingress(sgIDs func() []string, proto string, port int) Admitter

Ingress returns an Admitter that re-reads the target's group IDs on every connection, so membership and rule edits apply live. A nil Enforcer yields a nil Admitter, which Proxy treats as admit-all.

func (*Enforcer) SetSource

func (e *Enforcer) SetSource(s Source)

SetSource installs the security-group source.

type Flow

type Flow struct {
	Protocol string
	Peer     Peer
	Port     int
}

Flow is one connection attempt, described from the protected target's point of view.

type Group

type Group struct {
	ID      string
	Ingress []Rule
	Egress  []Rule
}

Group is a security group's rules.

type Peer

type Peer struct {
	Addr   netip.Addr
	Groups []string
}

Peer is the far end of a flow: its address and the security groups attached to it, if known.

type Proxy

type Proxy struct {
	// contains filtered or unexported fields
}

Proxy relays accepted connections to one upstream address, refusing clients its Admitter rejects.

func Front

func Front(ctx context.Context, bind, upstream string, admit Admitter) (*Proxy, error)

Front listens on bind and relays accepted clients to upstream, refusing those admit rejects; Close stops it.

func NewProxy

func NewProxy(ln net.Listener, upstream string, admit Admitter, dialer Dialer) *Proxy

NewProxy fronts upstream on ln. A nil admit admits every client; a nil dialer uses a plain net.Dialer.

func (*Proxy) Addr

func (p *Proxy) Addr() net.Addr

Addr is the listening address.

func (*Proxy) Close

func (p *Proxy) Close()

Close stops accepting, drops open connections and waits for the relays to finish.

func (*Proxy) Start

func (p *Proxy) Start()

Start runs the accept loop in the background; Close stops it.

type Rule

type Rule struct {
	Protocol string
	CIDRs    []netip.Prefix
	Groups   []string
	FromPort int
	ToPort   int
}

Rule is one ingress or egress permission. A rule matches a peer when any CIDR contains its address or any referenced group is attached to it.

type Source

type Source interface {
	// SecurityGroups returns the named groups; unknown IDs are omitted.
	SecurityGroups(ids []string) []Group
	// GroupsOfAddr lists the security groups attached to the interface owning addr.
	GroupsOfAddr(addr netip.Addr) []string
}

Source resolves live security-group state; EC2 implements it so rule changes take effect on the next connection without any push.

Directories

Path Synopsis
Package sgtest provides an in-memory sgfilter.Source for service tests.
Package sgtest provides an in-memory sgfilter.Source for service tests.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL