sdk

package
v0.6.0 Latest Latest
Warning

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

Go to latest
Published: Apr 24, 2026 License: GPL-3.0 Imports: 16 Imported by: 0

Documentation

Overview

Package sdk provides a typed Go client for the mirage management API.

Authentication

All API requests are authenticated via mutual TLS (mTLS). The client certificate and private key identify the operator; the CA certificate is used to pin the server's certificate instead of trusting the system roots.

Use NewClient to construct a Client:

client, err := sdk.NewClient(
	"https://203.0.113.1:443",  // address — TCP dial target
	"mgmt.example.com",         // secretHostname — TLS SNI and Host header
	certPEM, keyPEM, caCertPEM,
)

The address and secretHostname are intentionally separate: the TCP connection dials address directly so the operator's workstation does not need to resolve secretHostname via DNS. This allows the management interface to be hosted on a non-public hostname.

Client methods

Methods are grouped by resource domain:

  • Sessions — list, get, delete, export cookies, stream lifecycle events
  • Lures — CRUD, generate phishing URL, pause/unpause
  • Phishlets — enable/disable/hide/unhide, create/delete sub-phishlets
  • Blacklist — list, add, remove entries
  • BotGuard — manage JA4 signatures, update bot score threshold
  • System — status, reload

Package sdk provides types and a client for the mirage management API.

Index

Constants

View Source
const (
	// Sessions
	RouteSessionsStream = "/api/sessions/stream"
	RouteSessionExport  = "/api/sessions/{id}/export"
	RouteSession        = "/api/sessions/{id}"
	RouteSessions       = "/api/sessions"

	// Lures
	RouteLureURL   = "/api/lures/{id}/url"
	RouteLurePause = "/api/lures/{id}/pause"
	RouteLure      = "/api/lures/{id}"
	RouteLures     = "/api/lures"

	// Phishlets
	RoutePhishletHosts   = "/api/phishlets/{name}/hosts"
	RoutePhishletEnable  = "/api/phishlets/{name}/enable"
	RoutePhishletDisable = "/api/phishlets/{name}/disable"
	RoutePhishlet        = "/api/phishlets/{name}"
	RoutePhishlets       = "/api/phishlets"

	// Blacklist
	RouteBlacklistEntry = "/api/blacklist/{entry}"
	RouteBlacklist      = "/api/blacklist"

	// DNS
	RouteDNSProviders = "/api/dns/providers"
	RouteDNSZones     = "/api/dns/zones"
	RouteDNSSync      = "/api/dns/sync"

	// BotGuard
	RouteBotSignature  = "/api/botguard/signatures/{hash}"
	RouteBotSignatures = "/api/botguard/signatures"
	RouteBotThreshold  = "/api/botguard/threshold"

	// Notifications
	RouteNotificationTest       = "/api/notifications/channels/{id}/test"
	RouteNotificationChannel    = "/api/notifications/channels/{id}"
	RouteNotificationChannels   = "/api/notifications/channels"
	RouteNotificationEventTypes = "/api/notifications/event-types"

	// Operators
	RouteOperatorInvite = "/api/operators/invite"
	RouteOperator       = "/api/operators/{name}"
	RouteOperators      = "/api/operators"
	RouteEnroll         = "/api/enroll"

	// System
	RouteStatus = "/api/status"
	RouteReload = "/api/reload"
)

API route paths. The server registers these with a method prefix (e.g. "GET " + RouteSessions). The client resolves {param} placeholders using Resolve before making requests.

Variables

This section is empty.

Functions

func ResolveRoute

func ResolveRoute(route string, pairs ...string) string

ResolveRoute replaces {param} placeholders in a route pattern with concrete values. Parameters are passed as alternating name/value pairs:

ResolveRoute(RouteSession, "id", "abc123")  →  "/api/sessions/abc123"

Types

type AddBlacklistEntryRequest

type AddBlacklistEntryRequest struct {
	Value string `json:"value"`
}

func (AddBlacklistEntryRequest) Validate

func (r AddBlacklistEntryRequest) Validate() error

type AddBotSignatureRequest

type AddBotSignatureRequest struct {
	JA4Hash     string `json:"ja4_hash"`
	Description string `json:"description,omitempty"`
}

func (AddBotSignatureRequest) Validate

func (r AddBotSignatureRequest) Validate() error

type BlacklistEntryResponse

type BlacklistEntryResponse struct {
	Value string `json:"value"` // IP or CIDR
}

type BotSignatureResponse

type BotSignatureResponse struct {
	JA4Hash     string    `json:"ja4_hash"`
	Description string    `json:"description"`
	AddedAt     time.Time `json:"added_at"`
}

type ChannelType

type ChannelType string

ChannelType identifies the delivery backend for a notification channel.

const (
	ChannelWebhook ChannelType = "webhook"
	ChannelSlack   ChannelType = "slack"
)

type Client

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

Client is a typed HTTP client for the mirage management API. All requests are authenticated via the mutual TLS client certificate presented at construction time.

func NewClient

func NewClient(address, secretHostname string, certPEM, keyPEM, caCertPEM []byte) (*Client, error)

NewClient constructs a Client that connects to address using mTLS.

address is the server's IP/hostname and port (e.g. "https://1.2.3.4:443"). secretHostname is used for TLS SNI and the Host header; the TCP connection always dials address so the operator's workstation does not need to resolve secretHostname via DNS. certPEM and keyPEM are the operator's client certificate and private key. caCertPEM is the CA that signed the server's certificate, used for pinning.

func (*Client) AddBlacklistEntry

func (c *Client) AddBlacklistEntry(req AddBlacklistEntryRequest) (*BlacklistEntryResponse, error)

func (*Client) AddBotSignature

func (c *Client) AddBotSignature(req AddBotSignatureRequest) (*BotSignatureResponse, error)

func (*Client) CreateLure

func (c *Client) CreateLure(req CreateLureRequest) (*LureResponse, error)

func (*Client) CreateNotificationChannel

func (c *Client) CreateNotificationChannel(req CreateNotificationChannelRequest) (*NotificationChannelResponse, error)

func (*Client) DeleteLure

func (c *Client) DeleteLure(id string) error

func (*Client) DeleteNotificationChannel

func (c *Client) DeleteNotificationChannel(id string) error

func (*Client) DeleteOperator added in v0.2.0

func (c *Client) DeleteOperator(name string) error

func (*Client) DeleteSession

func (c *Client) DeleteSession(id string) error

func (*Client) DisablePhishlet

func (c *Client) DisablePhishlet(name string) (*PhishletResponse, error)

func (*Client) EnablePhishlet

func (c *Client) EnablePhishlet(name string, req EnablePhishletRequest) (*PhishletResponse, error)

func (*Client) ExportSessionCookies

func (c *Client) ExportSessionCookies(id string) ([]byte, error)

ExportSessionCookies returns the captured cookies for the session as raw JSON, in the format expected by the StorageAce browser import extension.

func (*Client) GenerateLureURL

func (c *Client) GenerateLureURL(id string, req GenerateURLRequest) (*GenerateURLResponse, error)

func (*Client) GetPhishlet

func (c *Client) GetPhishlet(name string) (*PhishletResponse, error)

func (*Client) GetSession

func (c *Client) GetSession(id string) (*SessionResponse, error)

func (*Client) InviteOperator added in v0.2.0

func (c *Client) InviteOperator(req InviteOperatorRequest) (*InviteOperatorResponse, error)

func (*Client) ListBlacklist

func (c *Client) ListBlacklist() (*PaginatedResponse[BlacklistEntryResponse], error)

func (*Client) ListBotSignatures

func (c *Client) ListBotSignatures() (*PaginatedResponse[BotSignatureResponse], error)

func (*Client) ListDNSProviders added in v0.4.0

func (c *Client) ListDNSProviders() ([]string, error)

func (*Client) ListDNSZones added in v0.4.0

func (c *Client) ListDNSZones() ([]DNSZoneResponse, error)

func (*Client) ListLures

func (c *Client) ListLures() (*PaginatedResponse[LureResponse], error)

func (*Client) ListNotificationChannels

func (c *Client) ListNotificationChannels() (*NotificationChannelList, error)

func (*Client) ListNotificationEventTypes added in v0.6.0

func (c *Client) ListNotificationEventTypes() ([]EventType, error)

func (*Client) ListOperators added in v0.2.0

func (c *Client) ListOperators() (*OperatorList, error)

func (*Client) ListPhishlets

func (c *Client) ListPhishlets() (*PaginatedResponse[PhishletResponse], error)

func (*Client) ListSessions

func (*Client) PauseLure

func (c *Client) PauseLure(id string, req PauseLureRequest) error

func (*Client) PushPhishlet added in v0.3.0

func (c *Client) PushPhishlet(req PushPhishletRequest) (*PhishletResponse, error)

func (*Client) Reload

func (c *Client) Reload() error

func (*Client) RemoveBlacklistEntry

func (c *Client) RemoveBlacklistEntry(entry string) error

func (*Client) RemoveBotSignature

func (c *Client) RemoveBotSignature(hash string) error

func (*Client) Status

func (c *Client) Status() (*StatusResponse, error)

func (*Client) StreamSessions

func (c *Client) StreamSessions() (<-chan SessionEvent, func(), error)

StreamSessions opens a Server-Sent Events connection and delivers session lifecycle events (created, updated, completed, deleted) to the returned channel. The channel is closed when the context-level done signal fires or the server closes the connection. Call the returned cancel function to stop streaming.

func (*Client) SyncDNS added in v0.4.0

func (c *Client) SyncDNS() error

func (*Client) TestNotificationChannel

func (c *Client) TestNotificationChannel(id string) error

func (*Client) UnpauseLure

func (c *Client) UnpauseLure(id string) error

func (*Client) UpdateBotThreshold

func (c *Client) UpdateBotThreshold(req UpdateBotThresholdRequest) error

func (*Client) UpdateLure

func (c *Client) UpdateLure(id string, req UpdateLureRequest) (*LureResponse, error)

type CreateLureRequest

type CreateLureRequest struct {
	Phishlet    string `json:"phishlet"`
	Path        string `json:"path,omitempty"`
	RedirectURL string `json:"redirect_url,omitempty"`
	SpoofURL    string `json:"spoof_url,omitempty"`
	UAFilter    string `json:"ua_filter,omitempty"`
}

func (CreateLureRequest) Validate

func (r CreateLureRequest) Validate() error

type CreateNotificationChannelRequest

type CreateNotificationChannelRequest struct {
	Type       ChannelType `json:"type"`
	URL        string      `json:"url"`
	AuthHeader string      `json:"auth_header,omitempty"` // webhook only
	Filter     []string    `json:"filter,omitempty"`      // event type filter; empty = all events
}

func (CreateNotificationChannelRequest) Validate

type DNSZoneResponse added in v0.4.0

type DNSZoneResponse struct {
	Zone     string `json:"zone"`
	Provider string `json:"provider"`
	IP       string `json:"ip"`
}

type EnablePhishletRequest

type EnablePhishletRequest struct {
	Hostname    string `json:"hostname"`
	DNSProvider string `json:"dns_provider"`
}

func (EnablePhishletRequest) Validate

func (r EnablePhishletRequest) Validate() error

type EnrollRequest added in v0.2.0

type EnrollRequest struct {
	Token  string `json:"token"`
	CSRPEM string `json:"csr_pem"`
}

func (EnrollRequest) Validate added in v0.2.0

func (r EnrollRequest) Validate() error

type EnrollResponse added in v0.2.0

type EnrollResponse struct {
	CertPEM   string `json:"cert_pem"`
	CACertPEM string `json:"ca_cert_pem"`
}

type ErrorResponse

type ErrorResponse struct {
	Error string `json:"error"`
}

ErrorResponse is returned by the API for all error responses.

type EventType

type EventType string

EventType identifies a domain event.

const (
	EventSessionCreated   EventType = "session.created"
	EventCredsCaptured    EventType = "session.creds_captured"
	EventTokensCaptured   EventType = "session.tokens_captured"
	EventSessionCompleted EventType = "session.completed"
	EventBotDetected      EventType = "botguard.detected"
	EventPhishletPushed   EventType = "phishlet.pushed"
	EventPhishletEnabled  EventType = "phishlet.enabled"
	EventDNSRecordSynced  EventType = "dns.synced"
)

func AllEventTypes

func AllEventTypes() []EventType

AllEventTypes returns the full set of known event types. Add new event types here — Valid() and the notification dispatcher derive from this list.

func (EventType) Valid

func (t EventType) Valid() bool

Valid reports whether t is a known event type.

type GenerateURLRequest

type GenerateURLRequest struct {
	Params map[string]string `json:"params"`
}

type GenerateURLResponse

type GenerateURLResponse struct {
	URL string `json:"url"`
}

type InviteOperatorRequest added in v0.2.0

type InviteOperatorRequest struct {
	Name string `json:"name"`
}

func (InviteOperatorRequest) Validate added in v0.2.0

func (r InviteOperatorRequest) Validate() error

type InviteOperatorResponse added in v0.2.0

type InviteOperatorResponse struct {
	Token string `json:"token"`
}

type LureResponse

type LureResponse struct {
	ID          string     `json:"id"`
	Phishlet    string     `json:"phishlet"`
	URL         string     `json:"url"`
	RedirectURL string     `json:"redirect_url"`
	SpoofURL    string     `json:"spoof_url"`
	UAFilter    string     `json:"ua_filter"`
	PausedUntil *time.Time `json:"paused_until,omitempty"`
}

type NotificationChannelList

type NotificationChannelList struct {
	Channels []NotificationChannelResponse `json:"channels"`
}

type NotificationChannelResponse

type NotificationChannelResponse struct {
	ID        string      `json:"id"`
	Type      ChannelType `json:"type"`
	URL       string      `json:"url"`
	Filter    []string    `json:"filter"`
	Enabled   bool        `json:"enabled"`
	CreatedAt time.Time   `json:"created_at"`
}

type OperatorList added in v0.2.0

type OperatorList struct {
	Operators []OperatorResponse `json:"operators"`
}

type OperatorResponse added in v0.2.0

type OperatorResponse struct {
	Name      string    `json:"name"`
	CreatedAt time.Time `json:"created_at"`
}

type PaginatedResponse

type PaginatedResponse[T any] struct {
	Items  []T `json:"items"`
	Total  int `json:"total"`
	Limit  int `json:"limit"`
	Offset int `json:"offset"`
}

PaginatedResponse wraps all list endpoint responses.

type PauseLureRequest

type PauseLureRequest struct {
	Duration string `json:"duration"` // Go duration string, e.g. "15m", "2h"
}

func (PauseLureRequest) Validate

func (r PauseLureRequest) Validate() error

type PhishletResponse

type PhishletResponse struct {
	Name        string `json:"name"`
	BaseDomain  string `json:"base_domain"`
	Hostname    string `json:"hostname"`
	DNSProvider string `json:"dns_provider"`
	SpoofURL    string `json:"spoof_url"`
	Enabled     bool   `json:"enabled"`
}

type PushPhishletRequest added in v0.3.0

type PushPhishletRequest struct {
	YAML string `json:"yaml"`
}

func (PushPhishletRequest) Validate added in v0.3.0

func (r PushPhishletRequest) Validate() error

type SessionEvent

type SessionEvent struct {
	Type    EventType
	Session SessionResponse
}

SessionEvent is delivered by StreamSessions for each lifecycle event.

type SessionFilter

type SessionFilter struct {
	Phishlet  string
	Completed *bool
	Since     *time.Time
	Until     *time.Time
	Limit     int
	Offset    int
}

SessionFilter scopes a ListSessions request.

type SessionResponse

type SessionResponse struct {
	ID           string                       `json:"id"`
	Phishlet     string                       `json:"phishlet"`
	LureID       string                       `json:"lure_id,omitempty"`
	RemoteAddr   string                       `json:"remote_addr,omitempty"`
	UserAgent    string                       `json:"user_agent,omitempty"`
	JA4Hash      string                       `json:"ja4_hash,omitempty"`
	BotScore     float64                      `json:"bot_score,omitempty"`
	Username     string                       `json:"username,omitempty"`
	Password     string                       `json:"password,omitempty"`
	Custom       map[string]string            `json:"custom,omitempty"`
	LureParams   map[string]string            `json:"lure_params,omitempty"`
	CookieTokens map[string]map[string]string `json:"cookie_tokens,omitempty"`
	BodyTokens   map[string]string            `json:"body_tokens,omitempty"`
	HTTPTokens   map[string]string            `json:"http_tokens,omitempty"`
	StartedAt    time.Time                    `json:"started_at"`
	CompletedAt  *time.Time                   `json:"completed_at,omitempty"`
}

type StatusResponse

type StatusResponse struct {
	Version        string    `json:"version"`
	Uptime         string    `json:"uptime"`
	UptimeSeconds  float64   `json:"uptime_seconds"`
	GoRoutines     int       `json:"goroutines"`
	TotalSessions  int       `json:"total_sessions"`
	ActiveSessions int       `json:"active_sessions"`
	StartedAt      time.Time `json:"started_at"`
}

type UpdateBotThresholdRequest

type UpdateBotThresholdRequest struct {
	Threshold float64 `json:"threshold"` // 0.0–1.0
}

func (UpdateBotThresholdRequest) Validate

func (r UpdateBotThresholdRequest) Validate() error

type UpdateLureRequest

type UpdateLureRequest struct {
	RedirectURL *string `json:"redirect_url,omitempty"`
	SpoofURL    *string `json:"spoof_url,omitempty"`
	UAFilter    *string `json:"ua_filter,omitempty"`
}

func (UpdateLureRequest) Validate

func (r UpdateLureRequest) Validate() error

Jump to

Keyboard shortcuts

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