netguard

Documentation

Overview

Package netguard는 외부 HTTP 대상과 dial 주소를 fail-closed로 검증합니다. IsBlockedAddr는 표준 private/loopback/link-local/ULA 대역을 막지만 CGNAT(100.64.0.0/10), benchmarking, NAT64, documentation 대역은 막지 않습니다. 강한 경계가 필요하면 Policy.AllowedHosts allowlist와 최초 요청 ValidateURL을 함께 쓰십시오. dial 경로는 IP+port만 강제합니다.

Index

• Variables
• func GuardedClient(client *http.Client, p Policy) *http.Client
• func GuardedDialContext(base func(context.Context, string, string) (net.Conn, error), p Policy) func(context.Context, string, string) (net.Conn, error)
• func GuardedTransport(base *http.Transport, p Policy) *http.Transport
• func IsBlockedAddr(addr netip.Addr) bool
• func IsBlockedIP(ip net.IP) bool
• func NormalizeHost(host string) string
• func RedirectPolicy(cfg RedirectConfig) func(req *http.Request, via []*http.Request) error
• type Policy
  • func (p Policy) ResolveHost(ctx context.Context, host string) ([]net.IP, error)
  • func (p Policy) ValidateTarget(ctx context.Context, target *url.URL) error
  • func (p Policy) ValidateURL(ctx context.Context, rawURL string) (*url.URL, error)
• type RedirectConfig
• type Resolver

Variables

var (
	// ErrBlockedIP는 대상이 차단된 IP 주소로 확인될 때의 오류다.
	ErrBlockedIP = errors.New("netguard: target resolves to a blocked IP address")
	// ErrHostNotAllowed는 대상 host가 allowlist 정책을 통과하지 못할 때의 오류다.
	ErrHostNotAllowed = errors.New("netguard: host not allowed")
	// ErrTooManyRedirects는 redirect 횟수가 정책 한도를 넘을 때의 오류다.
	ErrTooManyRedirects = errors.New("netguard: too many redirects")
	// ErrUnsupportedScheme는 URL scheme이 정책에서 허용되지 않을 때의 오류다.
	ErrUnsupportedScheme = errors.New("netguard: unsupported URL scheme")
)

Functions

func GuardedClient

func GuardedClient(client *http.Client, p Policy) *http.Client

GuardedClient는 http.Client transport에 Policy 검증을 적용한 복사본을 반환한다.

func GuardedDialContext

func GuardedDialContext(
	base func(context.Context, string, string) (net.Conn, error),
	p Policy,
) func(context.Context, string, string) (net.Conn, error)

GuardedDialContext는 dial 전에 host, port, IP 정책을 검증하는 dial 함수를 만든다.

func GuardedTransport

func GuardedTransport(base *http.Transport, p Policy) *http.Transport

GuardedTransport는 http.Transport의 dial 경로에 Policy 검증을 적용한다.

func IsBlockedAddr

func IsBlockedAddr(addr netip.Addr) bool

IsBlockedAddr는 주소가 private 또는 특수 목적 대역인지 검사한다.

func IsBlockedIP

func IsBlockedIP(ip net.IP) bool

IsBlockedIP는 IP가 private 또는 특수 목적 대역인지 검사한다.

func NormalizeHost

func NormalizeHost(host string) string

NormalizeHost는 비교용 host 문자열을 정규화한다.

func RedirectPolicy

func RedirectPolicy(cfg RedirectConfig) func(req *http.Request, via []*http.Request) error

RedirectPolicy는 redirect 대상도 Policy로 검증하는 CheckRedirect 함수다.

Types

type Policy

type Policy struct {
	// Resolver는 host lookup에 사용할 resolver다.
	Resolver Resolver
	// Timeout은 lookup과 기본 dial timeout이다.
	Timeout time.Duration
	// AllowPrivateNetworks는 private 및 특수 목적 IP 대역을 허용한다.
	AllowPrivateNetworks bool
	// AllowedHosts는 허용할 host allowlist다.
	AllowedHosts []string
	// AllowHost는 host별 추가 허용 여부를 판단한다.
	AllowHost func(string) bool
	// AllowedPorts는 허용할 destination port 목록이다.
	AllowedPorts []string
	// Schemes는 허용할 URL scheme 목록이다.
	Schemes []string
}

Policy는 외부 네트워크 대상 검증 규칙이다.

func (Policy) ResolveHost

func (p Policy) ResolveHost(ctx context.Context, host string) ([]net.IP, error)

ResolveHost는 정책 resolver로 host의 IP 주소 목록을 반환한다.

func (Policy) ValidateTarget

func (p Policy) ValidateTarget(ctx context.Context, target *url.URL) error

ValidateTarget은 파싱된 URL 대상이 정책에 맞는지 검증한다.

func (Policy) ValidateURL

func (p Policy) ValidateURL(ctx context.Context, rawURL string) (*url.URL, error)

ValidateURL은 URL 문자열을 파싱하고 정책에 맞는지 검증한다.

type RedirectConfig

type RedirectConfig struct {
	// Policy는 redirect target 검증에 사용할 정책이다.
	Policy Policy
	// MaxRedirects는 허용할 최대 redirect 수다.
	MaxRedirects int
	// DisableFollow는 redirect follow를 비활성화한다.
	DisableFollow bool
	// ForwardHeaders는 cross-host redirect에도 기존 header를 유지한다.
	ForwardHeaders bool
	// CheckRedirect는 정책 검증 뒤 실행할 추가 redirect hook이다.
	CheckRedirect func(req *http.Request, via []*http.Request) error
}

RedirectConfig는 HTTP redirect 검증과 header 전달 정책이다.

type Resolver

type Resolver interface {
	// LookupIP는 host의 IP 주소 목록을 반환한다.
	LookupIP(ctx context.Context, network, host string) ([]net.IP, error)
}

Resolver는 host를 IP 주소 목록으로 확인한다.