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
- func ResolveRoute(route string, pairs ...string) string
- type AddBlacklistEntryRequest
- type AddBotSignatureRequest
- type BlacklistEntryResponse
- type BotSignatureResponse
- type ChannelType
- type Client
- func (c *Client) AddBlacklistEntry(req AddBlacklistEntryRequest) (*BlacklistEntryResponse, error)
- func (c *Client) AddBotSignature(req AddBotSignatureRequest) (*BotSignatureResponse, error)
- func (c *Client) CreateLure(req CreateLureRequest) (*LureResponse, error)
- func (c *Client) CreateNotificationChannel(req CreateNotificationChannelRequest) (*NotificationChannelResponse, error)
- func (c *Client) DeleteLure(id string) error
- func (c *Client) DeleteNotificationChannel(id string) error
- func (c *Client) DeleteOperator(name string) error
- func (c *Client) DeleteSession(id string) error
- func (c *Client) DisablePhishlet(name string) (*PhishletResponse, error)
- func (c *Client) EnablePhishlet(name string, req EnablePhishletRequest) (*PhishletResponse, error)
- func (c *Client) ExportSessionCookies(id string) ([]byte, error)
- func (c *Client) GenerateLureURL(id string, req GenerateURLRequest) (*GenerateURLResponse, error)
- func (c *Client) GetPhishlet(name string) (*PhishletResponse, error)
- func (c *Client) GetSession(id string) (*SessionResponse, error)
- func (c *Client) InviteOperator(req InviteOperatorRequest) (*InviteOperatorResponse, error)
- func (c *Client) ListBlacklist() (*PaginatedResponse[BlacklistEntryResponse], error)
- func (c *Client) ListBotSignatures() (*PaginatedResponse[BotSignatureResponse], error)
- func (c *Client) ListDNSProviders() ([]string, error)
- func (c *Client) ListDNSZones() ([]DNSZoneResponse, error)
- func (c *Client) ListLures() (*PaginatedResponse[LureResponse], error)
- func (c *Client) ListNotificationChannels() (*NotificationChannelList, error)
- func (c *Client) ListNotificationEventTypes() ([]EventType, error)
- func (c *Client) ListOperators() (*OperatorList, error)
- func (c *Client) ListPhishlets() (*PaginatedResponse[PhishletResponse], error)
- func (c *Client) ListSessions(f SessionFilter) (*PaginatedResponse[SessionResponse], error)
- func (c *Client) PauseLure(id string, req PauseLureRequest) error
- func (c *Client) PushPhishlet(req PushPhishletRequest) (*PhishletResponse, error)
- func (c *Client) Reload() error
- func (c *Client) RemoveBlacklistEntry(entry string) error
- func (c *Client) RemoveBotSignature(hash string) error
- func (c *Client) Status() (*StatusResponse, error)
- func (c *Client) StreamSessions() (<-chan SessionEvent, func(), error)
- func (c *Client) SyncDNS() error
- func (c *Client) TestNotificationChannel(id string) error
- func (c *Client) UnpauseLure(id string) error
- func (c *Client) UpdateBotThreshold(req UpdateBotThresholdRequest) error
- func (c *Client) UpdateLure(id string, req UpdateLureRequest) (*LureResponse, error)
- type CreateLureRequest
- type CreateNotificationChannelRequest
- type DNSZoneResponse
- type EnablePhishletRequest
- type EnrollRequest
- type EnrollResponse
- type ErrorResponse
- type EventType
- type GenerateURLRequest
- type GenerateURLResponse
- type InviteOperatorRequest
- type InviteOperatorResponse
- type LureResponse
- type NotificationChannelList
- type NotificationChannelResponse
- type OperatorList
- type OperatorResponse
- type PaginatedResponse
- type PauseLureRequest
- type PhishletResponse
- type PushPhishletRequest
- type SessionEvent
- type SessionFilter
- type SessionResponse
- type StatusResponse
- type UpdateBotThresholdRequest
- type UpdateLureRequest
Constants ¶
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 ¶
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 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 ¶
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 (*Client) DeleteNotificationChannel ¶
func (*Client) DeleteOperator ¶ added in v0.2.0
func (*Client) DeleteSession ¶
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 ¶
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 (*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 (*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 (c *Client) ListSessions(f SessionFilter) (*PaginatedResponse[SessionResponse], error)
func (*Client) PushPhishlet ¶ added in v0.3.0
func (c *Client) PushPhishlet(req PushPhishletRequest) (*PhishletResponse, error)
func (*Client) RemoveBlacklistEntry ¶
func (*Client) RemoveBotSignature ¶
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) TestNotificationChannel ¶
func (*Client) UnpauseLure ¶
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 ¶
func (r CreateNotificationChannelRequest) Validate() error
type DNSZoneResponse ¶ added in v0.4.0
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
func (EnrollRequest) Validate ¶ added in v0.2.0
func (r EnrollRequest) Validate() error
type EnrollResponse ¶ added in v0.2.0
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.
type GenerateURLRequest ¶
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 NotificationChannelList ¶
type NotificationChannelList struct {
Channels []NotificationChannelResponse `json:"channels"`
}
type OperatorList ¶ added in v0.2.0
type OperatorList struct {
Operators []OperatorResponse `json:"operators"`
}
type OperatorResponse ¶ added in v0.2.0
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 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 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