Documentation
¶
Overview ¶
Package remoteaccess provides provider-neutral session plumbing for agent-routed interactive access. Protocol adapters such as SSH or Proxmox console own target-specific dialing; Manager owns session frame routing.
Index ¶
- Constants
- Variables
- func DesktopAuditMetadata(payload DesktopOpenPayload) map[string]string
- func DesktopFrameAuditMetadata(frame DesktopFrame) map[string]string
- func DesktopLifecycleAuditMetadata(payload DesktopOpenPayload, eventType string, timestampUnix int64, ...) (map[string]string, error)
- func DesktopTerminationAuditMetadata(frame DesktopFrame) map[string]string
- func DialSSHClient(ctx context.Context, cfg SSHConfig) (*ssh.Client, error)
- func EncodeDesktopFramePayload(frame DesktopFrame, policy DesktopScreenPolicy) ([]byte, error)
- func EncodeDesktopFramePayloadWithPolicy(frame DesktopFrame, policy DesktopScreenPolicy, ...) ([]byte, error)
- func EncodeDesktopMediaFrame(frame DesktopMediaFrame, policy DesktopScreenPolicy) ([]byte, error)
- func NormalizeRDPAdapterPath(path string) string
- func PlatformEnhancedRecordingAvailable() bool
- func RDPAdapterBinaryAvailable(path string) bool
- func RDPAdapterReady(path string) bool
- func ResolveRDPAdapterPath(path string) (string, error)
- func ValidateDesktopContentRecording(frame DesktopFrame, policy DesktopRecordingPolicy) error
- func ValidateDesktopFrame(frame DesktopFrame, policy DesktopScreenPolicy) error
- func ValidateDesktopFrameWithPolicy(frame DesktopFrame, policy DesktopScreenPolicy, ...) error
- func ValidateDesktopMediaAck(ack DesktopMediaAck, sessionBindingID, mediaSessionID string) error
- func ValidateDesktopMediaFrame(frame DesktopMediaFrame, policy DesktopScreenPolicy) error
- func ValidateDesktopRouteBinding(target DesktopTarget, localAgentID string, currentGatewayID string) error
- func ValidateDesktopSessionLifetime(policy DesktopScreenPolicy, startUnix int64, lastActivityUnix int64, ...) error
- type AdapterRegistry
- type ApplicationClosePayload
- type ApplicationDataDirection
- type ApplicationDataPayload
- type ApplicationErrorPayload
- type ApplicationHTTPAdapter
- type ApplicationHTTPAdapterOptions
- type ApplicationHTTPResult
- type ApplicationOpenPayload
- type ApplicationOutcomePayload
- type ApplicationProgressPayload
- type ApplicationRequestPayload
- type ApplicationResponseMetadataPayload
- type ApplicationScheme
- type DesktopAdapterInput
- type DesktopAdapterOpenRequest
- type DesktopAdapterRuntime
- type DesktopAdapterSession
- type DesktopCredentialGrant
- func NormalizeDesktopCredentialGrant(grant DesktopCredentialGrant, target DesktopTarget) (DesktopCredentialGrant, error)
- func NormalizeDesktopCredentialGrantAt(grant DesktopCredentialGrant, target DesktopTarget, nowUnix int64) (DesktopCredentialGrant, error)
- func ValidateDesktopOpenCredentialGrant(payload DesktopOpenPayload, sessionID string, nowUnix int64) (*DesktopCredentialGrant, error)
- type DesktopCredentialPolicy
- type DesktopFrame
- func DecodeDesktopFramePayload(data []byte, policy DesktopScreenPolicy) (DesktopFrame, error)
- func DecodeDesktopFramePayloadForSession(data []byte, policy DesktopScreenPolicy, sessionID string) (DesktopFrame, error)
- func DecodeDesktopFramePayloadForSessionWithPolicy(data []byte, policy DesktopScreenPolicy, redirection DesktopRedirectionPolicy, ...) (DesktopFrame, error)
- func DecodeDesktopFramePayloadWithPolicy(data []byte, policy DesktopScreenPolicy, redirection DesktopRedirectionPolicy) (DesktopFrame, error)
- type DesktopFrameQuotaWindow
- type DesktopInputEvent
- type DesktopMediaAck
- type DesktopMediaAckHandler
- type DesktopMediaAckHandlerRegistrar
- type DesktopMediaCreditWindow
- func (w *DesktopMediaCreditWindow) Adjust(creditBytes uint64)
- func (w *DesktopMediaCreditWindow) ApplyAck(ack DesktopMediaAck, sessionBindingID, mediaSessionID string) error
- func (w DesktopMediaCreditWindow) CanSend(frame DesktopMediaFrame) bool
- func (w DesktopMediaCreditWindow) CloseReason() string
- func (w *DesktopMediaCreditWindow) Consume(frame DesktopMediaFrame) error
- func (w DesktopMediaCreditWindow) LastAcceptedSeq() (uint64, bool)
- func (w DesktopMediaCreditWindow) MaxAckCreditBytes() uint64
- func (w DesktopMediaCreditWindow) MaxChunkBytes() uint32
- func (w DesktopMediaCreditWindow) Paused() bool
- func (w DesktopMediaCreditWindow) QualityLevel() string
- func (w DesktopMediaCreditWindow) RemainingBytes() uint64
- type DesktopMediaFrame
- type DesktopMediaFrameParts
- type DesktopMediaFrameStaticFields
- type DesktopMediaSender
- type DesktopOpenPayload
- type DesktopQuality
- type DesktopRDPAdapter
- type DesktopRecordingPolicy
- type DesktopRedirectionPolicy
- type DesktopRoute
- type DesktopScreenPolicy
- type DesktopSessionGuard
- func (g *DesktopSessionGuard) ApplyMediaAck(window *DesktopMediaCreditWindow, ack DesktopMediaAck, mediaSessionID string, ...) error
- func (g *DesktopSessionGuard) LastActivityUnix() int64
- func (g *DesktopSessionGuard) SessionID() string
- func (g *DesktopSessionGuard) Target() DesktopTarget
- func (g *DesktopSessionGuard) ValidateContentRecording(frame DesktopFrame) error
- func (g *DesktopSessionGuard) ValidateFrame(frame DesktopFrame, localAgentID string, currentGatewayID string, ...) error
- func (g *DesktopSessionGuard) ValidateMediaAck(ack DesktopMediaAck, mediaSessionID string, localAgentID string, ...) error
- func (g *DesktopSessionGuard) ValidateMediaFrame(frame DesktopMediaFrame, localAgentID string, currentGatewayID string, ...) error
- type DesktopTLSPolicy
- type DesktopTarget
- type DesktopUpstream
- type EnhancedEvent
- type EnhancedEventSource
- type EnhancedRecorder
- type EnhancedRecording
- type EnhancedRecordingPolicy
- type EnhancedRecordingSession
- type ErrorReason
- type FileTransferAckPayload
- type FileTransferDataPayload
- type FileTransferDirection
- type FileTransferEntry
- type FileTransferErrorPayload
- type FileTransferOperation
- type FileTransferOutcomePayload
- type FileTransferPolicy
- type FileTransferPolicyDecision
- type FileTransferPolicyInput
- type FileTransferProgressPayload
- type FileTransferRequestPayload
- type FileTransferResult
- type FileTransferStatus
- type FileTransferSymlinkMode
- type Frame
- type FrameAuthenticator
- type KnownHostsStore
- type LinuxProcEnhancedEventSource
- type LinuxProcOption
- type Manager
- type ManagerConfig
- type Opener
- type PTY
- type RDPAdapterCapabilities
- type RemoteAccessStreamStatus
- type SFTPAdapter
- type SFTPClient
- type SFTPDialer
- type SFTPFile
- type SSHAuth
- type SSHConfig
- type SSHDialer
- type SSHHostKeyApproval
- type SSHOpenOptions
- type SSHOpenPayload
- type SSHSession
- type SSHTarget
- type Sender
- type SourceEnhancedRecorder
- type TCPAdapter
- type TCPAdapterOptions
- type TCPClosePayload
- type TCPDataDirection
- type TCPDataPayload
- type TCPDialer
- type TCPErrorPayload
- type TCPOpenPayload
- type TCPOutcomePayload
- type TCPProgressPayload
Constants ¶
const ( ProtocolProxmoxConsole = "proxmox_console" ProtocolVSphereConsole = "vsphere_console" ProtocolRDP = "rdp" ProtocolApp = "app" ProtocolTCP = "tcp" ProtocolDatabase = "database" ProtocolKubernetes = "kubernetes" ProtocolDesktop = "desktop" ProtocolOT = "ot" )
const ( FrameTypeApplicationOpen = "app_open" FrameTypeApplicationRequest = "app_request" FrameTypeApplicationResponseMetadata = "app_response_metadata" FrameTypeApplicationData = "app_data" FrameTypeApplicationProgress = "app_progress" FrameTypeApplicationClose = "app_close" FrameTypeApplicationError = "app_error" FrameTypeApplicationOutcome = "app_outcome" FrameTypeTCPOpen = "tcp_open" FrameTypeTCPData = "tcp_data" FrameTypeTCPProgress = "tcp_progress" FrameTypeTCPClose = "tcp_close" FrameTypeTCPError = "tcp_error" FrameTypeTCPOutcome = "tcp_outcome" ApplicationSchemeHTTP ApplicationScheme = "http" ApplicationSchemeHTTPS ApplicationScheme = "https" ApplicationDataDirectionRequest ApplicationDataDirection = "request" ApplicationDataDirectionResponse ApplicationDataDirection = "response" TCPDataDirectionClient TCPDataDirection = "client" TCPDataDirectionUpstream TCPDataDirection = "upstream" ApplicationStatusStarted RemoteAccessStreamStatus = "started" ApplicationStatusInProgress RemoteAccessStreamStatus = "in_progress" ApplicationStatusCompleted RemoteAccessStreamStatus = "completed" ApplicationStatusDenied RemoteAccessStreamStatus = "denied" ApplicationStatusFailed RemoteAccessStreamStatus = "failed" ApplicationStatusQuotaExhausted RemoteAccessStreamStatus = "quota_exhausted" ApplicationStatusClosed RemoteAccessStreamStatus = "closed" TCPStatusStarted RemoteAccessStreamStatus = ApplicationStatusStarted TCPStatusInProgress RemoteAccessStreamStatus = ApplicationStatusInProgress TCPStatusCompleted RemoteAccessStreamStatus = ApplicationStatusCompleted TCPStatusDenied RemoteAccessStreamStatus = ApplicationStatusDenied TCPStatusFailed RemoteAccessStreamStatus = ApplicationStatusFailed TCPStatusQuotaExhausted RemoteAccessStreamStatus = ApplicationStatusQuotaExhausted TCPStatusClosed RemoteAccessStreamStatus = ApplicationStatusClosed )
const ( DesktopCredentialModeDomainDelegation = "domain_delegation" DesktopCredentialModeMemoryUser = "memory_user" DesktopCredentialModeSmartCard = "smart_card" DesktopCredentialModeBrokeredSecret = "brokered_secret" DesktopTLSModeVerify = "verify" DesktopTLSModePinnedCA = "pinned_ca" DesktopTLSModeInsecure = "insecure" DesktopTLSModeSystem = "system" DesktopTLSModeTOFU = "tofu" DesktopDefaultTLSPolicy = DesktopTLSModeVerify DesktopNLAModeRequired = "required" DesktopNLAModeDisabled = "disabled" DesktopDefaultNLAPolicy = DesktopNLAModeRequired DesktopDefaultRDPPort = 3389 DesktopDefaultMaxWidth = 1920 DesktopDefaultMaxHeight = 1080 DesktopDefaultFrameRate = 30 DesktopDefaultBitrateBPS = 8_000_000 DesktopDefaultIdleSec = 900 DesktopDefaultTTLSec = 3600 DesktopMaxCABundlePEM = 256 * 1024 DesktopMaxWidth = 7680 DesktopMaxHeight = 4320 DesktopMaxFrameRate = 60 DesktopMaxBitrateBPS = 100_000_000 DesktopMaxFrameData = 1_048_576 DesktopMaxInputTokenSize = 128 DesktopMaxAuditReason = 256 DesktopClipboardModeDisabled = "disabled" DesktopClipboardModeTextToRemote = "text_to_remote" DesktopClipboardModeTextToBrowser = "text_to_browser" DesktopClipboardModeTextBoth = "text_bidirectional" DesktopFrameTypeUpdate = "desktop.update" DesktopFrameTypeInput = "desktop.input" DesktopFrameTypeResize = "desktop.resize" DesktopFrameTypeClipboard = "desktop.clipboard" DesktopFrameTypeQuality = "desktop.quality" DesktopFrameTypeDisconnect = "desktop.disconnect" DesktopLifecycleEventOpen = "desktop.session.open" DesktopLifecycleEventReady = "desktop.session.ready" DesktopLifecycleEventClose = "desktop.session.close" DesktopLifecycleEventError = "desktop.session.error" DesktopLifecycleEventRevoked = "desktop.session.revoked" DesktopInputKindKey = "key" DesktopInputKindPointer = "pointer" DesktopInputKindFocus = "focus" DesktopClipboardDirectionToRemote = "to_remote" DesktopClipboardDirectionToBrowser = "to_browser" )
const ( DefaultRDPAdapterBinary = "serviceradar-rdp-adapter" RDPAdapterCapabilitiesArg = "--capabilities" RDPAdapterCapabilitiesSchema = "serviceradar.rdp.helper.capabilities.v1" RDPAdapterProbeTimeout = 5 * time.Second RDPAdapterMinProtocolVersion = 1 )
const ( DesktopMediaMagic = "SRDP" DesktopMediaVersion = 1 DesktopMediaHeaderSize = 48 DesktopMediaMaxMetadata = 64 * 1024 DesktopMediaMaxCloseReason = 256 DesktopMediaFlagKeyframe uint8 = 0x01 DesktopMediaFlagFullFrame uint8 = 0x02 DesktopMediaFlagCursorUpdate uint8 = 0x04 DesktopMediaFlagEndOfStream uint8 = 0x08 DesktopMediaFlagDiscontinuity uint8 = 0x10 DesktopMediaAllowedFlags = DesktopMediaFlagKeyframe | DesktopMediaFlagFullFrame | DesktopMediaFlagCursorUpdate | DesktopMediaFlagEndOfStream | DesktopMediaFlagDiscontinuity DesktopMediaPayloadVideo = "video" DesktopMediaPayloadDirtyRect = "dirty_rect" DesktopMediaPayloadTile = "tile" DesktopMediaPayloadCursor = "cursor" DesktopMediaPayloadMetadata = "metadata" DesktopMediaControlTypeAck = "desktop_media_ack" DesktopMediaQualityAuto = "auto" DesktopMediaQualityLow = "low" DesktopMediaDefaultInitialCreditBytes = 4 * 1024 * 1024 DesktopMediaDefaultMaxChunkBytes = 256 * 1024 DesktopMediaDefaultMaxAckCreditBytes = 4 * 1024 * 1024 )
const ( CapabilityRemoteAccess = "remote_access" CapabilityRemoteAccessSSH = "remote_access.ssh" CapabilityRemoteAccessApp = "remote_access.app" CapabilityRemoteAccessTCP = "remote_access.tcp" CapabilityRemoteAccessFile = "remote_access.file_transfer" CapabilityRemoteAccessSFTP = "remote_access.sftp" CapabilityRemoteAccessDesktop = "remote_access.desktop" CapabilityRemoteAccessRDP = "remote_access.rdp" CapabilityRemoteAccessRecording = "remote_access.recording" CapabilityRemoteAccessBPF = "remote_access.bpf" )
const ( FrameTypeEnhancedEvent = "enhanced_event" EnhancedEventCommand = "command" EnhancedEventFile = "file" EnhancedEventNetwork = "network" EnhancedEventLoss = "loss" )
const ( ProtocolSFTP = "sftp" FrameTypeFileTransferRequest = "file_transfer_request" FrameTypeFileTransferProgress = "file_transfer_progress" FrameTypeFileTransferData = "file_transfer_data" FrameTypeFileTransferAck = "file_transfer_ack" FrameTypeFileTransferError = "file_transfer_error" FrameTypeFileTransferOutcome = "file_transfer_outcome" FileTransferOperationList FileTransferOperation = "list" FileTransferOperationStat FileTransferOperation = "stat" FileTransferOperationDownload FileTransferOperation = "download" FileTransferOperationUpload FileTransferOperation = "upload" FileTransferOperationMkdir FileTransferOperation = "mkdir" FileTransferOperationRename FileTransferOperation = "rename" FileTransferOperationRemove FileTransferOperation = "remove" FileTransferOperationChmod FileTransferOperation = "chmod" FileTransferOperationChown FileTransferOperation = "chown" FileTransferDirectionRead FileTransferDirection = "read" FileTransferDirectionWrite FileTransferDirection = "write" FileTransferDirectionManage FileTransferDirection = "manage" FileTransferStatusRequested FileTransferStatus = "requested" FileTransferStatusStarted FileTransferStatus = "started" FileTransferStatusInProgress FileTransferStatus = "in_progress" FileTransferStatusCompleted FileTransferStatus = "completed" FileTransferStatusDenied FileTransferStatus = "denied" FileTransferStatusFailed FileTransferStatus = "failed" FileTransferStatusCanceled FileTransferStatus = "canceled" FileTransferStatusQuotaExhausted FileTransferStatus = "quota_exhausted" FileTransferStatusApprovalPending FileTransferStatus = "approval_pending" )
const ( FrameTypeOpen = "open" FrameTypeReady = "ready" FrameTypeData = "data" FrameTypeResize = "resize" FrameTypeHeartbeat = "heartbeat" FrameTypeClose = "close" FrameTypeError = "error" FrameTypeOutcome = "outcome" MaxTerminalCols = 500 MaxTerminalRows = 200 MaxTerminalFrameData = 65_536 MaxOpenFrameData = 262_144 )
const ( ProtocolSSH = "ssh" SSHCredentialModeUserPresent = "user_present" SSHCredentialModeSSHCertificate = "ssh_certificate" )
const (
EnhancedExecutionManagedTarget = "managed_target"
)
const (
FrameAuthAlgorithm = "hmac-sha256-v1"
)
Variables ¶
var ( ErrInvalidApplicationTargetID = errors.New("invalid application target id") ErrInvalidApplicationSessionID = errors.New("invalid application session id") ErrInvalidApplicationScheme = errors.New("invalid application scheme") ErrInvalidApplicationUpstreamHost = errors.New("invalid application upstream host") ErrInvalidApplicationUpstreamPort = errors.New("invalid application upstream port") ErrInvalidApplicationRequestID = errors.New("invalid application request id") ErrInvalidApplicationMethod = errors.New("invalid application method") ErrInvalidApplicationPath = errors.New("invalid application path") ErrInvalidApplicationDataDirection = errors.New("invalid application data direction") ErrInvalidApplicationSequence = errors.New("invalid application sequence") ErrInvalidApplicationStatus = errors.New("invalid application status") ErrInvalidTCPTargetID = errors.New("invalid tcp target id") ErrInvalidTCPSessionID = errors.New("invalid tcp session id") ErrInvalidTCPConnectionID = errors.New("invalid tcp connection id") ErrInvalidTCPUpstreamHost = errors.New("invalid tcp upstream host") ErrInvalidTCPUpstreamPort = errors.New("invalid tcp upstream port") ErrInvalidTCPDataDirection = errors.New("invalid tcp data direction") ErrInvalidTCPSequence = errors.New("invalid tcp sequence") ErrInvalidTCPStatus = errors.New("invalid tcp status") )
var ( ErrApplicationMethodNotAllowed = errors.New("application method not allowed") ErrApplicationPathNotAllowed = errors.New("application path not allowed") ErrApplicationRequestTooLarge = errors.New("application request body exceeds quota") ErrApplicationResponseTooLarge = errors.New("application response body exceeds quota") ErrApplicationAdapterNil = errors.New("application http adapter is nil") ErrApplicationSessionMismatch = errors.New("application request session does not match open session") )
var ( ErrInvalidDesktopTarget = errors.New("invalid desktop target") ErrInvalidDesktopFrame = errors.New("invalid desktop frame") ErrDesktopContentRecord = errors.New("desktop content recording disabled") ErrDesktopQuotaExceeded = errors.New("desktop quota exceeded") ErrDesktopSessionExpired = errors.New("desktop session expired") ErrDesktopRouteLost = errors.New("desktop route lost") )
var ( ErrDesktopAdapterClosed = errors.New("desktop adapter closed") )
var ( ErrInvalidDesktopMediaFrame = errors.New("invalid desktop media frame") ErrInvalidDesktopMediaAck = errors.New("invalid desktop media ack") ErrDesktopMediaNoCredit = errors.New("desktop media credit exhausted") )
var ( ErrInvalidFileTransferID = errors.New("invalid file transfer id") ErrInvalidFileTransferSessionID = errors.New("invalid file transfer session id") ErrInvalidFileTransferOperation = errors.New("invalid file transfer operation") ErrInvalidFileTransferDirection = errors.New("invalid file transfer direction") ErrInvalidFileTransferPath = errors.New("invalid file transfer path") ErrFileTransferDestinationMissing = errors.New("file transfer destination path is required") ErrInvalidFileTransferSequence = errors.New("invalid file transfer sequence") ErrInvalidFileTransferOffset = errors.New("invalid file transfer offset") )
var ( ErrFileTransferPolicyDenied = errors.New("file transfer denied by policy") ErrInvalidFileTransferPathRule = errors.New("invalid file transfer path rule") ErrInvalidFileTransferSymlinkMode = errors.New("invalid file transfer symlink mode") ErrFileTransferApprovalRequired = errors.New("file transfer approval is required") ErrFileTransferQuotaExceeded = errors.New("file transfer quota exceeded") )
var ( ErrInvalidFrameAuth = errors.New("invalid remote access frame auth") ErrUnsupportedFrameAuth = errors.New("unsupported remote access frame auth") )
var ( ErrSessionExists = errors.New("remote access session is already active") ErrSessionNotActive = errors.New("remote access session is not active") ErrUnsupportedFrame = errors.New("unsupported remote access frame type") ErrInvalidFrameSize = errors.New("invalid remote access frame size") )
var ( ErrSFTPInputRequired = errors.New("sftp input is required") ErrSFTPInputEmpty = errors.New("sftp upload file must not be empty") ErrSFTPOutputRequired = errors.New("sftp output is required") ErrSFTPOperationMetadataRequired = errors.New("sftp operation metadata is required") ErrSFTPDirectionOperationMismatch = errors.New("sftp direction does not match operation") ErrUnsupportedFileTransferOperation = errors.New("unsupported file transfer operation") )
var ( ErrMissingSSHTargetHost = errors.New("missing SSH target host") ErrInvalidSSHTargetPort = errors.New("invalid SSH target port") ErrInvalidSSHFieldSize = errors.New("invalid SSH field size") ErrSSHUsernameRequired = errors.New("ssh username is required") ErrSSHCredentialRequired = errors.New("ssh private key or password is required") ErrSSHCertificateRequiresKey = errors.New("ssh certificate requires matching private key") ErrSSHCertificateKeyMismatch = errors.New("ssh certificate public key does not match private key") ErrInvalidSSHCertificate = errors.New("invalid ssh certificate") ErrUnsupportedSSHHostKeyPolicy = errors.New("unsupported ssh_host_key_policy") ErrSSHSessionOutputChannelOverflow = errors.New("ssh session output channel overflow") )
var ( // ErrSSHHostKeyUnknown reports that no entry exists yet for the target in // the agent-local known-hosts store. The operator can review the offered // fingerprint and enroll it with the trust-on-first-use policy. ErrSSHHostKeyUnknown = errors.New("ssh host key is not trusted") // ErrSSHHostKeyMismatch reports that the target offered a key that differs // from the one already pinned for it or from an explicit retry approval. ErrSSHHostKeyMismatch = errors.New("ssh host key does not match the trusted entry") )
Host-key verification failures reach the operator as a session close reason, which is the only channel the console frame vocabulary offers. The two classes below therefore carry a stable, documented sentence shape so the browser can tell an enrollable first contact apart from a key that changed under a host that was already trusted. Only the first is ever offered for acceptance; the second is the man-in-the-middle case and stays a hard close.
var ( ErrUnsupportedSSHProtocol = errors.New("unsupported remote access ssh protocol") ErrInvalidSSHOpenPayload = errors.New("invalid ssh open payload") ErrUnsupportedSSHCredentialMode = errors.New("unsupported ssh credential mode") ErrSSHCertificateRequired = errors.New("ssh certificate is required") ErrSSHOpenSessionMismatch = errors.New("ssh open payload session_id does not match frame") ErrSSHOpenProtocolMismatch = errors.New("ssh open payload protocol does not match frame") ErrSSHOpenAgentMismatch = errors.New("ssh open payload agent_id does not match frame metadata") ErrSSHOpenGatewayMismatch = errors.New("ssh open payload gateway_id does not match frame metadata") )
var ( ErrTCPAdapterNil = errors.New("tcp adapter is nil") ErrTCPDirectionNotAllowed = errors.New("tcp frame direction not allowed") ErrTCPBytesInQuotaExceeded = errors.New("tcp bytes in quota exceeded") ErrTCPBytesOutQuotaExceeded = errors.New("tcp bytes out quota exceeded") ErrTCPAdapterClosed = errors.New("tcp adapter is closed") ErrInvalidTCPReadChunkSize = errors.New("invalid tcp read chunk size") ErrTCPSessionMismatch = errors.New("tcp frame binding does not match open connection") ErrTCPSequenceOutOfOrder = errors.New("tcp frame sequence is not greater than the previous client frame") )
var ErrEnhancedRecordingTargetBoundaryRequired = errors.New("target-side enhanced recording requires managed target execution")
var ErrUnsupportedProtocolAdapter = errors.New("unsupported remote access protocol adapter")
Functions ¶
func DesktopAuditMetadata ¶ added in v1.2.69
func DesktopAuditMetadata(payload DesktopOpenPayload) map[string]string
DesktopAuditMetadata returns metadata that is safe to persist for desktop session audit/recording records. It intentionally omits usernames, passwords, credential secret references, and caller-supplied metadata maps.
func DesktopFrameAuditMetadata ¶ added in v1.2.69
func DesktopFrameAuditMetadata(frame DesktopFrame) map[string]string
DesktopFrameAuditMetadata returns frame metadata suitable for audit and recording records without retaining screen pixels, clipboard data, key names, button names, or other frame payload contents.
func DesktopLifecycleAuditMetadata ¶ added in v1.2.69
func DesktopLifecycleAuditMetadata( payload DesktopOpenPayload, eventType string, timestampUnix int64, outcome string, ) (map[string]string, error)
DesktopLifecycleAuditMetadata returns safe metadata for desktop session lifecycle records. It includes target/policy posture plus a fixed event type and capped single-line outcome, but it omits credential material and caller-supplied metadata.
func DesktopTerminationAuditMetadata ¶ added in v1.2.69
func DesktopTerminationAuditMetadata(frame DesktopFrame) map[string]string
DesktopTerminationAuditMetadata returns safe metadata for desktop close/error outcomes. It includes a capped, single-line reason while keeping generic frame audit metadata free of close reasons by default.
func DialSSHClient ¶ added in v1.2.60
DialSSHClient opens a real SSH client using the same credential custody and host-key trust path as SSH PTY sessions. Non-PTY protocols such as SFTP must use this instead of creating their own x/crypto/ssh client configuration.
func EncodeDesktopFramePayload ¶ added in v1.2.69
func EncodeDesktopFramePayload(frame DesktopFrame, policy DesktopScreenPolicy) ([]byte, error)
EncodeDesktopFramePayload validates and serializes a typed desktop frame for transport inside the existing ConsoleFrame data field.
func EncodeDesktopFramePayloadWithPolicy ¶ added in v1.2.69
func EncodeDesktopFramePayloadWithPolicy( frame DesktopFrame, policy DesktopScreenPolicy, redirection DesktopRedirectionPolicy, ) ([]byte, error)
EncodeDesktopFramePayloadWithPolicy validates and serializes a typed desktop frame with an explicit redirection policy.
func EncodeDesktopMediaFrame ¶ added in v1.2.69
func EncodeDesktopMediaFrame(frame DesktopMediaFrame, policy DesktopScreenPolicy) ([]byte, error)
func NormalizeRDPAdapterPath ¶ added in v1.2.69
NormalizeRDPAdapterPath returns the configured helper path, or the default helper binary name when the agent config leaves the path unset.
func PlatformEnhancedRecordingAvailable ¶
func PlatformEnhancedRecordingAvailable() bool
PlatformEnhancedRecordingAvailable reports whether this host has a ServiceRadar-owned BPF collector that can satisfy required BPF policies. The procfs collector returned by NewPlatformEnhancedRecorder is an optional/fallback collector and must not advertise the BPF capability.
func RDPAdapterBinaryAvailable ¶ added in v1.2.69
func RDPAdapterReady ¶ added in v1.2.69
func ResolveRDPAdapterPath ¶ added in v1.2.69
ResolveRDPAdapterPath resolves the local per-session RDP helper that backs the concrete IronRDP adapter. Agents must not advertise remote_access.rdp unless this helper can be executed.
func ValidateDesktopContentRecording ¶ added in v1.2.69
func ValidateDesktopContentRecording(frame DesktopFrame, policy DesktopRecordingPolicy) error
ValidateDesktopContentRecording returns nil only when policy explicitly allows retaining the content represented by the frame.
func ValidateDesktopFrame ¶ added in v1.2.69
func ValidateDesktopFrame(frame DesktopFrame, policy DesktopScreenPolicy) error
func ValidateDesktopFrameWithPolicy ¶ added in v1.2.69
func ValidateDesktopFrameWithPolicy( frame DesktopFrame, policy DesktopScreenPolicy, redirection DesktopRedirectionPolicy, ) error
ValidateDesktopFrameWithPolicy validates a desktop frame against both screen and redirection policy. Use this for any path that accepts clipboard or other local resource redirection frames.
func ValidateDesktopMediaAck ¶ added in v1.2.69
func ValidateDesktopMediaAck(ack DesktopMediaAck, sessionBindingID, mediaSessionID string) error
func ValidateDesktopMediaFrame ¶ added in v1.2.69
func ValidateDesktopMediaFrame(frame DesktopMediaFrame, policy DesktopScreenPolicy) error
func ValidateDesktopRouteBinding ¶ added in v1.2.69
func ValidateDesktopRouteBinding(target DesktopTarget, localAgentID string, currentGatewayID string) error
ValidateDesktopRouteBinding verifies that a still-running desktop session is on the selected agent and, when supplied, selected gateway route.
func ValidateDesktopSessionLifetime ¶ added in v1.2.69
func ValidateDesktopSessionLifetime( policy DesktopScreenPolicy, startUnix int64, lastActivityUnix int64, nowUnix int64, ) error
ValidateDesktopSessionLifetime enforces the idle and absolute TTL policy for an adapter session. Timestamps are Unix seconds; callers should update lastActivityUnix whenever user input, screen traffic, or explicit heartbeat activity is accepted for the session.
Types ¶
type AdapterRegistry ¶
type AdapterRegistry struct {
// contains filtered or unexported fields
}
AdapterRegistry resolves protocol names to protocol-specific PTY openers. It is intentionally credential-agnostic; each adapter receives only the session-scoped open frame and must enforce its own payload validation.
func DefaultAdapterRegistry ¶
func DefaultAdapterRegistry(sshOptions SSHOpenOptions) *AdapterRegistry
DefaultAdapterRegistry returns the protocols that are implemented today.
func NewAdapterRegistry ¶
func NewAdapterRegistry() *AdapterRegistry
NewAdapterRegistry creates an empty adapter registry.
func (*AdapterRegistry) Opener ¶
func (r *AdapterRegistry) Opener() Opener
Opener returns a manager-compatible opener that dispatches by Frame.Protocol.
func (*AdapterRegistry) Register ¶
func (r *AdapterRegistry) Register(protocol string, opener Opener)
Register adds or replaces a protocol opener. Empty protocols and nil openers are ignored to keep callers from accidentally registering a catch-all.
type ApplicationClosePayload ¶ added in v1.2.67
type ApplicationClosePayload struct {
RequestID string `json:"request_id,omitempty"`
SessionID string `json:"session_id"`
Reason string `json:"reason,omitempty"`
}
ApplicationClosePayload reports an orderly application request or session close.
func (ApplicationClosePayload) Validate ¶ added in v1.2.67
func (p ApplicationClosePayload) Validate() error
type ApplicationDataDirection ¶ added in v1.2.67
type ApplicationDataDirection string
ApplicationDataDirection marks whether bounded bytes flow toward the application upstream or back toward the browser.
func (ApplicationDataDirection) Valid ¶ added in v1.2.67
func (d ApplicationDataDirection) Valid() bool
Valid returns true when the application data direction is part of the frame contract.
type ApplicationDataPayload ¶ added in v1.2.67
type ApplicationDataPayload struct {
RequestID string `json:"request_id"`
SessionID string `json:"session_id"`
Direction ApplicationDataDirection `json:"direction"`
Sequence uint64 `json:"sequence"`
Data []byte `json:"data,omitempty"`
EOF bool `json:"eof,omitempty"`
}
ApplicationDataPayload carries one bounded request or response body chunk.
func (ApplicationDataPayload) Validate ¶ added in v1.2.67
func (p ApplicationDataPayload) Validate() error
type ApplicationErrorPayload ¶ added in v1.2.67
type ApplicationErrorPayload struct {
RequestID string `json:"request_id,omitempty"`
SessionID string `json:"session_id"`
Status RemoteAccessStreamStatus `json:"status"`
Code string `json:"code"`
Message string `json:"message,omitempty"`
}
ApplicationErrorPayload reports a denied, failed, or quota-exhausted application action.
func (ApplicationErrorPayload) Validate ¶ added in v1.2.67
func (p ApplicationErrorPayload) Validate() error
type ApplicationHTTPAdapter ¶ added in v1.2.67
type ApplicationHTTPAdapter struct {
// contains filtered or unexported fields
}
func NewApplicationHTTPAdapter ¶ added in v1.2.67
func NewApplicationHTTPAdapter(open ApplicationOpenPayload, opts ApplicationHTTPAdapterOptions) (*ApplicationHTTPAdapter, error)
func (*ApplicationHTTPAdapter) Close ¶ added in v1.2.67
func (a *ApplicationHTTPAdapter) Close()
func (*ApplicationHTTPAdapter) Execute ¶ added in v1.2.67
func (a *ApplicationHTTPAdapter) Execute( ctx context.Context, request ApplicationRequestPayload, body []byte, ) (ApplicationHTTPResult, error)
func (*ApplicationHTTPAdapter) MaxRequestBodyBytes ¶ added in v1.2.67
func (a *ApplicationHTTPAdapter) MaxRequestBodyBytes() int64
type ApplicationHTTPAdapterOptions ¶ added in v1.2.67
type ApplicationHTTPResult ¶ added in v1.2.67
type ApplicationHTTPResult struct {
Metadata ApplicationResponseMetadataPayload
Data ApplicationDataPayload
Progress ApplicationProgressPayload
Outcome ApplicationOutcomePayload
}
type ApplicationOpenPayload ¶ added in v1.2.67
type ApplicationOpenPayload struct {
TargetID string `json:"target_id"`
SessionID string `json:"session_id"`
Scheme ApplicationScheme `json:"scheme"`
UpstreamHost string `json:"upstream_host"`
UpstreamPort int `json:"upstream_port"`
HostHeader string `json:"host_header,omitempty"`
SNI string `json:"sni,omitempty"`
TLSPolicy map[string]any `json:"tls_policy,omitempty"`
CABundleRef string `json:"ca_bundle_ref,omitempty"`
AllowedMethods []string `json:"allowed_methods,omitempty"`
AllowedPathPrefixes []string `json:"allowed_path_prefixes,omitempty"`
HeaderPolicy map[string]any `json:"header_policy,omitempty"`
CookiePolicy map[string]any `json:"cookie_policy,omitempty"`
QuotaPolicy map[string]any `json:"quota_policy,omitempty"`
ApprovalID string `json:"approval_id,omitempty"`
RecordingPolicy map[string]any `json:"recording_policy,omitempty"`
EnhancedRecordingPolicy map[string]any `json:"enhanced_recording_policy,omitempty"`
Metadata map[string]string `json:"metadata,omitempty"`
}
ApplicationOpenPayload is carried by FrameTypeApplicationOpen after the control plane has resolved a registered target. It is never accepted directly from browser intent.
func (ApplicationOpenPayload) Validate ¶ added in v1.2.67
func (p ApplicationOpenPayload) Validate() error
type ApplicationOutcomePayload ¶ added in v1.2.67
type ApplicationOutcomePayload struct {
SessionID string `json:"session_id"`
TargetID string `json:"target_id"`
Status RemoteAccessStreamStatus `json:"status"`
RequestCount int64 `json:"request_count,omitempty"`
RequestBytes int64 `json:"request_bytes,omitempty"`
ResponseBytes int64 `json:"response_bytes,omitempty"`
FailureReason string `json:"failure_reason,omitempty"`
}
ApplicationOutcomePayload reports durable metadata for audit and replay.
func (ApplicationOutcomePayload) Validate ¶ added in v1.2.67
func (p ApplicationOutcomePayload) Validate() error
type ApplicationProgressPayload ¶ added in v1.2.67
type ApplicationProgressPayload struct {
RequestID string `json:"request_id,omitempty"`
SessionID string `json:"session_id"`
Status RemoteAccessStreamStatus `json:"status"`
RequestBytes int64 `json:"request_bytes,omitempty"`
ResponseBytes int64 `json:"response_bytes,omitempty"`
}
ApplicationProgressPayload reports lifecycle and byte-count metadata.
func (ApplicationProgressPayload) Validate ¶ added in v1.2.67
func (p ApplicationProgressPayload) Validate() error
type ApplicationRequestPayload ¶ added in v1.2.67
type ApplicationRequestPayload struct {
RequestID string `json:"request_id"`
SessionID string `json:"session_id"`
Method string `json:"method"`
Path string `json:"path"`
Query string `json:"query,omitempty"`
Headers map[string][]string `json:"headers,omitempty"`
}
ApplicationRequestPayload carries request metadata only. Request bodies use FrameTypeApplicationData and must stay bounded by adapter quota policy.
func (ApplicationRequestPayload) Validate ¶ added in v1.2.67
func (p ApplicationRequestPayload) Validate() error
type ApplicationResponseMetadataPayload ¶ added in v1.2.67
type ApplicationResponseMetadataPayload struct {
RequestID string `json:"request_id"`
SessionID string `json:"session_id"`
StatusCode int `json:"status_code"`
Headers map[string][]string `json:"headers,omitempty"`
ContentType string `json:"content_type,omitempty"`
}
ApplicationResponseMetadataPayload carries response headers and status without body bytes.
func (ApplicationResponseMetadataPayload) Validate ¶ added in v1.2.67
func (p ApplicationResponseMetadataPayload) Validate() error
type ApplicationScheme ¶ added in v1.2.67
type ApplicationScheme string
ApplicationScheme identifies the trusted upstream scheme selected from target policy.
func (ApplicationScheme) Valid ¶ added in v1.2.67
func (s ApplicationScheme) Valid() bool
Valid returns true when the application upstream scheme is supported.
type DesktopAdapterInput ¶ added in v1.2.69
type DesktopAdapterInput interface {
SendDesktopFrame(context.Context, DesktopFrame) error
}
DesktopAdapterInput receives browser control/input frames after the session guard has validated route, lifetime, redirection, and quota policy.
type DesktopAdapterOpenRequest ¶ added in v1.2.69
type DesktopAdapterOpenRequest struct {
SessionID string
ActorID string
LocalAgentID string
CurrentGatewayID string
StartUnix int64
Target DesktopTarget
CredentialGrant *DesktopCredentialGrant
MediaSender DesktopMediaSender
}
type DesktopAdapterRuntime ¶ added in v1.2.69
type DesktopAdapterRuntime struct {
LocalAgentID string
CurrentGatewayID string
NowUnix func() int64
NowUnixNano func() int64
Adapter DesktopRDPAdapter
}
DesktopAdapterRuntime validates a trusted desktop open frame and delegates to a concrete protocol adapter. It intentionally keeps validation outside the adapter implementation so every adapter enters through the same policy path.
func (DesktopAdapterRuntime) OpenRDP ¶ added in v1.2.69
func (r DesktopAdapterRuntime) OpenRDP( ctx context.Context, frame Frame, mediaSender DesktopMediaSender, ) (DesktopAdapterSession, error)
type DesktopAdapterSession ¶ added in v1.2.69
type DesktopAdapterSession interface {
DesktopAdapterInput
Close(context.Context, string) error
}
DesktopAdapterSession is an active protocol adapter instance. It owns the target connection and must release any per-session credential material during Close.
type DesktopCredentialGrant ¶ added in v1.2.69
type DesktopCredentialGrant struct {
Mode string `json:"mode"`
Username string `json:"username,omitempty"`
Password string `json:"password,omitempty"`
CredentialSecretRef string `json:"credential_secret_ref,omitempty"`
ActorID string `json:"actor_id,omitempty"`
SessionID string `json:"session_id,omitempty"`
TargetID string `json:"target_id,omitempty"`
RouteID string `json:"route_id,omitempty"`
ExpiresUnix int64 `json:"expires_unix,omitempty"`
}
func NormalizeDesktopCredentialGrant ¶ added in v1.2.69
func NormalizeDesktopCredentialGrant( grant DesktopCredentialGrant, target DesktopTarget, ) (DesktopCredentialGrant, error)
func NormalizeDesktopCredentialGrantAt ¶ added in v1.2.69
func NormalizeDesktopCredentialGrantAt( grant DesktopCredentialGrant, target DesktopTarget, nowUnix int64, ) (DesktopCredentialGrant, error)
NormalizeDesktopCredentialGrantAt validates a desktop credential grant at a caller-provided Unix timestamp. Tests and adapters with trusted clocks can use this to make brokered-secret TTL decisions explicit.
func ValidateDesktopOpenCredentialGrant ¶ added in v1.2.69
func ValidateDesktopOpenCredentialGrant( payload DesktopOpenPayload, sessionID string, nowUnix int64, ) (*DesktopCredentialGrant, error)
ValidateDesktopOpenCredentialGrant normalizes a desktop open-frame credential grant and enforces session binding for credential modes that carry secrets.
func (*DesktopCredentialGrant) DropSensitive ¶ added in v1.2.69
func (grant *DesktopCredentialGrant) DropSensitive()
DropSensitive clears session credential material from the grant once an adapter no longer needs it. Password is string-backed because grants arrive over JSON, so this releases references rather than promising allocator-level memory scrubbing.
type DesktopCredentialPolicy ¶ added in v1.2.69
type DesktopFrame ¶ added in v1.2.69
type DesktopFrame struct {
SessionID string `json:"session_id"`
Protocol string `json:"protocol"`
FrameType string `json:"frame_type"`
Width uint32 `json:"width,omitempty"`
Height uint32 `json:"height,omitempty"`
Encoding string `json:"encoding,omitempty"`
Data []byte `json:"data,omitempty"`
Input *DesktopInputEvent `json:"input,omitempty"`
Quality *DesktopQuality `json:"quality,omitempty"`
Direction string `json:"direction,omitempty"`
Reason string `json:"reason,omitempty"`
Timestamp int64 `json:"timestamp,omitempty"`
Metadata map[string]string `json:"metadata,omitempty"`
}
DesktopFrame is the protocol-neutral graphical frame contract used by RDP and future desktop adapters. It is intentionally separate from terminal PTY byte frames.
func DecodeDesktopFramePayload ¶ added in v1.2.69
func DecodeDesktopFramePayload(data []byte, policy DesktopScreenPolicy) (DesktopFrame, error)
DecodeDesktopFramePayload decodes and validates a typed desktop frame carried inside the existing ConsoleFrame data field.
func DecodeDesktopFramePayloadForSession ¶ added in v1.2.69
func DecodeDesktopFramePayloadForSession( data []byte, policy DesktopScreenPolicy, sessionID string, ) (DesktopFrame, error)
DecodeDesktopFramePayloadForSession decodes a typed desktop frame and rejects frames that are not bound to the expected remote-access session.
func DecodeDesktopFramePayloadForSessionWithPolicy ¶ added in v1.2.69
func DecodeDesktopFramePayloadForSessionWithPolicy( data []byte, policy DesktopScreenPolicy, redirection DesktopRedirectionPolicy, sessionID string, ) (DesktopFrame, error)
DecodeDesktopFramePayloadForSessionWithPolicy decodes a typed desktop frame, applies redirection policy, and rejects frames not bound to the expected remote-access session.
func DecodeDesktopFramePayloadWithPolicy ¶ added in v1.2.69
func DecodeDesktopFramePayloadWithPolicy( data []byte, policy DesktopScreenPolicy, redirection DesktopRedirectionPolicy, ) (DesktopFrame, error)
DecodeDesktopFramePayloadWithPolicy decodes and validates a typed desktop frame with an explicit redirection policy.
type DesktopFrameQuotaWindow ¶ added in v1.2.69
type DesktopFrameQuotaWindow struct {
// contains filtered or unexported fields
}
DesktopFrameQuotaWindow tracks per-second screen update quotas for adapter code before the dedicated desktop media stream carries production traffic.
func NewDesktopFrameQuotaWindow ¶ added in v1.2.69
func NewDesktopFrameQuotaWindow(policy DesktopScreenPolicy) DesktopFrameQuotaWindow
func (*DesktopFrameQuotaWindow) Consume ¶ added in v1.2.69
func (w *DesktopFrameQuotaWindow) Consume(frame DesktopFrame, nowUnixNano int64) error
Consume applies frame-rate and bitrate quotas to desktop update frames. Non-screen frames are ignored here and still use their normal validators.
type DesktopInputEvent ¶ added in v1.2.69
type DesktopMediaAck ¶ added in v1.2.69
type DesktopMediaAck struct {
SessionBindingID string `json:"session_binding_id"`
MediaSessionID string `json:"media_session_id"`
LastAcceptedSeq uint64 `json:"last_accepted_seq"`
CreditBytes uint64 `json:"credit_bytes"`
QualityLevel string `json:"quality_level,omitempty"`
Pause bool `json:"pause,omitempty"`
Resume bool `json:"resume,omitempty"`
CloseReason string `json:"close_reason,omitempty"`
}
func DecodeDesktopMediaAckMessage ¶ added in v1.2.69
func DecodeDesktopMediaAckMessage(data []byte, sessionBindingID, mediaSessionID string) (DesktopMediaAck, error)
type DesktopMediaAckHandler ¶ added in v1.2.69
type DesktopMediaAckHandler func(context.Context, DesktopMediaAck) error
type DesktopMediaAckHandlerRegistrar ¶ added in v1.2.69
type DesktopMediaAckHandlerRegistrar interface {
SetDesktopMediaAckHandler(DesktopMediaAckHandler)
}
DesktopMediaAckHandlerRegistrar lets adapter-facing media sinks route browser/gateway backpressure acknowledgements back to protocol adapters.
type DesktopMediaCreditWindow ¶ added in v1.2.69
type DesktopMediaCreditWindow struct {
// contains filtered or unexported fields
}
func NewDesktopMediaCreditWindow ¶ added in v1.2.69
func NewDesktopMediaCreditWindow(initialCreditBytes uint64, maxChunkBytes uint32) (DesktopMediaCreditWindow, error)
func (*DesktopMediaCreditWindow) Adjust ¶ added in v1.2.69
func (w *DesktopMediaCreditWindow) Adjust(creditBytes uint64)
func (*DesktopMediaCreditWindow) ApplyAck ¶ added in v1.2.69
func (w *DesktopMediaCreditWindow) ApplyAck(ack DesktopMediaAck, sessionBindingID, mediaSessionID string) error
func (DesktopMediaCreditWindow) CanSend ¶ added in v1.2.69
func (w DesktopMediaCreditWindow) CanSend(frame DesktopMediaFrame) bool
func (DesktopMediaCreditWindow) CloseReason ¶ added in v1.2.69
func (w DesktopMediaCreditWindow) CloseReason() string
func (*DesktopMediaCreditWindow) Consume ¶ added in v1.2.69
func (w *DesktopMediaCreditWindow) Consume(frame DesktopMediaFrame) error
func (DesktopMediaCreditWindow) LastAcceptedSeq ¶ added in v1.2.69
func (w DesktopMediaCreditWindow) LastAcceptedSeq() (uint64, bool)
func (DesktopMediaCreditWindow) MaxAckCreditBytes ¶ added in v1.2.69
func (w DesktopMediaCreditWindow) MaxAckCreditBytes() uint64
func (DesktopMediaCreditWindow) MaxChunkBytes ¶ added in v1.2.69
func (w DesktopMediaCreditWindow) MaxChunkBytes() uint32
func (DesktopMediaCreditWindow) Paused ¶ added in v1.2.69
func (w DesktopMediaCreditWindow) Paused() bool
func (DesktopMediaCreditWindow) QualityLevel ¶ added in v1.2.69
func (w DesktopMediaCreditWindow) QualityLevel() string
func (DesktopMediaCreditWindow) RemainingBytes ¶ added in v1.2.69
func (w DesktopMediaCreditWindow) RemainingBytes() uint64
type DesktopMediaFrame ¶ added in v1.2.69
type DesktopMediaFrame struct {
SessionBindingID string
MediaSessionID string
Sequence uint64
TimestampUnixNano int64
Width uint32
Height uint32
PayloadFamily string
Encoding string
Metadata []byte
Payload []byte
Flags uint8
}
DesktopMediaFrame is the compact binary envelope shared by the Go agent, gateway/core, and browser worker. It matches web-ng's SRDP browser parser.
func DecodeDesktopMediaFrame ¶ added in v1.2.69
func DecodeDesktopMediaFrame(data []byte, policy DesktopScreenPolicy) (DesktopMediaFrame, error)
func DecodeDesktopMediaFrameView ¶ added in v1.2.69
func DecodeDesktopMediaFrameView(data []byte, policy DesktopScreenPolicy) (DesktopMediaFrame, error)
DecodeDesktopMediaFrameView decodes a frame without copying metadata or payload. Callers must keep data alive and immutable for as long as the returned frame is used.
type DesktopMediaFrameParts ¶ added in v1.2.69
type DesktopMediaFrameParts struct {
Header []byte
SessionBindingID []byte
MediaSessionID []byte
Encoding []byte
Metadata []byte
Payload []byte
}
DesktopMediaFrameParts exposes the SRDP frame as ordered byte slices for vectored writes. Header can be caller-owned and reused across frames; Metadata and Payload alias the frame input and must remain immutable until the write completes.
func BuildDesktopMediaFrameParts ¶ added in v1.2.69
func BuildDesktopMediaFrameParts( frame DesktopMediaFrame, policy DesktopScreenPolicy, header []byte, ) (DesktopMediaFrameParts, error)
func BuildDesktopMediaFramePartsWithStaticFields ¶ added in v1.2.69
func BuildDesktopMediaFramePartsWithStaticFields( frame DesktopMediaFrame, policy DesktopScreenPolicy, header []byte, staticFields DesktopMediaFrameStaticFields, ) (DesktopMediaFrameParts, error)
func (DesktopMediaFrameParts) AppendTo ¶ added in v1.2.69
func (p DesktopMediaFrameParts) AppendTo(dst []byte) []byte
func (DesktopMediaFrameParts) Len ¶ added in v1.2.69
func (p DesktopMediaFrameParts) Len() int
type DesktopMediaFrameStaticFields ¶ added in v1.2.69
type DesktopMediaFrameStaticFields struct {
SessionBindingID string
MediaSessionID string
Encoding string
// contains filtered or unexported fields
}
DesktopMediaFrameStaticFields stores per-session frame fields in both string and byte form so high-volume media loops can avoid re-encoding stable values for every screen update.
func NewDesktopMediaFrameStaticFields ¶ added in v1.2.69
func NewDesktopMediaFrameStaticFields( sessionBindingID, mediaSessionID, encoding string, ) (DesktopMediaFrameStaticFields, error)
type DesktopMediaSender ¶ added in v1.2.69
type DesktopMediaSender interface {
SendDesktopMediaFrame(context.Context, DesktopMediaFrame) error
}
DesktopMediaSender is the adapter-facing media sink for SRDP screen updates. Implementations typically wrap the dedicated desktop media gRPC stream. Metadata and Payload may alias adapter-owned buffers; senders must synchronously serialize or copy bytes needed after SendDesktopMediaFrame returns and must not retain the frame slices.
type DesktopOpenPayload ¶ added in v1.2.69
type DesktopOpenPayload struct {
Schema string `json:"schema,omitempty"`
ActorID string `json:"actor_id,omitempty"`
Target DesktopTarget `json:"target"`
CredentialGrant *DesktopCredentialGrant `json:"credential_grant,omitempty"`
Metadata map[string]string `json:"metadata,omitempty"`
}
DesktopOpenPayload is the agent-side open-frame contract for graphical desktop protocols. It contains trusted target policy compiled by core, not browser-selected upstream settings.
func DecodeDesktopOpenFrameForAgent ¶ added in v1.2.69
func DecodeDesktopOpenFrameForAgent(frame Frame, localAgentID string) (DesktopOpenPayload, error)
DecodeDesktopOpenFrameForAgent decodes a trusted desktop open frame and enforces that the selected route is bound to the local agent before an adapter dials the target.
func DecodeDesktopOpenPayload ¶ added in v1.2.69
func DecodeDesktopOpenPayload(data []byte) (DesktopOpenPayload, error)
DecodeDesktopOpenPayload decodes and validates a trusted desktop open-frame payload before an agent adapter dials the target.
type DesktopQuality ¶ added in v1.2.69
type DesktopRDPAdapter ¶ added in v1.2.69
type DesktopRDPAdapter interface {
Open(context.Context, DesktopAdapterOpenRequest) (DesktopAdapterSession, error)
}
DesktopRDPAdapter is the narrow seam for the future IronRDP bridge. Open receives an already-normalized, route-bound target and memory-only credential grant. Implementations must not persist credential material.
type DesktopRecordingPolicy ¶ added in v1.2.69
type DesktopRedirectionPolicy ¶ added in v1.2.69
type DesktopRoute ¶ added in v1.2.69
type DesktopScreenPolicy ¶ added in v1.2.69
type DesktopScreenPolicy struct {
MaxWidth uint32 `json:"max_width"`
MaxHeight uint32 `json:"max_height"`
ColorDepth uint32 `json:"color_depth,omitempty"`
FrameRate uint32 `json:"frame_rate"`
BitrateBPS uint32 `json:"bitrate_bps"`
IdleSeconds uint32 `json:"idle_seconds"`
TTLSeconds uint32 `json:"ttl_seconds"`
}
type DesktopSessionGuard ¶ added in v1.2.69
type DesktopSessionGuard struct {
// contains filtered or unexported fields
}
DesktopSessionGuard centralizes the per-frame checks an adapter must perform while a desktop session is active. It keeps route binding, lifetime, redirection policy, and update-frame quotas on one path so adapter code does not accidentally validate only part of the session contract.
func NewDesktopSessionGuard ¶ added in v1.2.69
func NewDesktopSessionGuard(sessionID string, target DesktopTarget, startUnix int64) (DesktopSessionGuard, error)
func (*DesktopSessionGuard) ApplyMediaAck ¶ added in v1.2.69
func (g *DesktopSessionGuard) ApplyMediaAck( window *DesktopMediaCreditWindow, ack DesktopMediaAck, mediaSessionID string, localAgentID string, currentGatewayID string, nowUnix int64, ) error
ApplyMediaAck validates a browser/gateway acknowledgement against the active session guard and applies it to the sender credit window as one operation. This keeps route, lifetime, session/media binding, and replay checks on the same path before sender flow-control state mutates.
func (*DesktopSessionGuard) LastActivityUnix ¶ added in v1.2.69
func (g *DesktopSessionGuard) LastActivityUnix() int64
func (*DesktopSessionGuard) SessionID ¶ added in v1.2.69
func (g *DesktopSessionGuard) SessionID() string
func (*DesktopSessionGuard) Target ¶ added in v1.2.69
func (g *DesktopSessionGuard) Target() DesktopTarget
func (*DesktopSessionGuard) ValidateContentRecording ¶ added in v1.2.69
func (g *DesktopSessionGuard) ValidateContentRecording(frame DesktopFrame) error
ValidateContentRecording checks whether retaining the sensitive content from an already accepted frame is allowed by this session's recording policy. Metadata-only audit paths do not need this check; screen pixels and clipboard bytes must pass it before being persisted or exported.
func (*DesktopSessionGuard) ValidateFrame ¶ added in v1.2.69
func (g *DesktopSessionGuard) ValidateFrame( frame DesktopFrame, localAgentID string, currentGatewayID string, nowUnix int64, nowUnixNano int64, ) error
ValidateFrame applies the current session guard before an adapter consumes or emits a desktop frame. Accepted frames update last-activity time after all validation and quota checks succeed.
func (*DesktopSessionGuard) ValidateMediaAck ¶ added in v1.2.69
func (g *DesktopSessionGuard) ValidateMediaAck( ack DesktopMediaAck, mediaSessionID string, localAgentID string, currentGatewayID string, nowUnix int64, ) error
ValidateMediaAck applies the session guard to a browser/gateway SRDP media acknowledgement before the ack mutates sender credit-window state.
func (*DesktopSessionGuard) ValidateMediaFrame ¶ added in v1.2.69
func (g *DesktopSessionGuard) ValidateMediaFrame( frame DesktopMediaFrame, localAgentID string, currentGatewayID string, nowUnix int64, ) error
ValidateMediaFrame applies the session guard to a dedicated SRDP media frame before the gateway or adapter accepts screen/cursor/media payloads.
type DesktopTLSPolicy ¶ added in v1.2.69
type DesktopTarget ¶ added in v1.2.69
type DesktopTarget struct {
TargetID string `json:"target_id"`
DisplayName string `json:"display_name,omitempty"`
DeviceUID string `json:"device_uid,omitempty"`
Protocol string `json:"protocol"`
Route DesktopRoute `json:"route"`
Upstream DesktopUpstream `json:"upstream"`
TLS DesktopTLSPolicy `json:"tls"`
Credential DesktopCredentialPolicy `json:"credential"`
Screen DesktopScreenPolicy `json:"screen"`
Redirection DesktopRedirectionPolicy `json:"redirection"`
ApprovalRequired bool `json:"approval_required,omitempty"`
Recording DesktopRecordingPolicy `json:"recording"`
Metadata map[string]string `json:"metadata,omitempty"`
}
DesktopTarget describes one registered desktop target and its immutable per-session policy snapshot.
func NormalizeDesktopTarget ¶ added in v1.2.69
func NormalizeDesktopTarget(target DesktopTarget) (DesktopTarget, error)
NormalizeDesktopTarget applies secure defaults and validates the registered desktop target policy snapshot.
type DesktopUpstream ¶ added in v1.2.69
type EnhancedEvent ¶
type EnhancedEvent struct {
EventType string `json:"event_type"`
SessionID string `json:"session_id"`
Protocol string `json:"protocol,omitempty"`
ActorID string `json:"actor_id,omitempty"`
AgentID string `json:"agent_id,omitempty"`
GatewayID string `json:"gateway_id,omitempty"`
Target map[string]string `json:"target,omitempty"`
CredentialCustodyMode string `json:"credential_custody_mode,omitempty"`
TimestampUnixNano int64 `json:"timestamp_unix_nano"`
PID int `json:"pid,omitempty"`
PPID int `json:"ppid,omitempty"`
UID int `json:"uid,omitempty"`
GID int `json:"gid,omitempty"`
CommandPath string `json:"command_path,omitempty"`
Argv []string `json:"argv,omitempty"`
CWD string `json:"cwd,omitempty"`
ExitStatus *int `json:"exit_status,omitempty"`
FilePath string `json:"file_path,omitempty"`
FileOperation string `json:"file_operation,omitempty"`
NetworkProtocol string `json:"network_protocol,omitempty"`
SourceAddress string `json:"source_address,omitempty"`
SourcePort int `json:"source_port,omitempty"`
DestinationAddress string `json:"destination_address,omitempty"`
DestinationPort int `json:"destination_port,omitempty"`
Result string `json:"result,omitempty"`
DroppedEvents uint64 `json:"dropped_events,omitempty"`
Metadata map[string]string `json:"metadata,omitempty"`
}
EnhancedEvent is the clean-room normalized event shape emitted by future Linux collectors. It intentionally excludes terminal bytes and file contents.
type EnhancedEventSource ¶
type EnhancedEventSource interface {
Start(context.Context, EnhancedRecordingSession) (<-chan EnhancedEvent, func(context.Context) error, error)
}
EnhancedEventSource starts a concrete host-event collector. Linux BPF probes implement this boundary; tests can inject synthetic event sources without carrying kernel or privilege requirements.
type EnhancedRecorder ¶
type EnhancedRecorder interface {
Start(context.Context, EnhancedRecordingSession) (EnhancedRecording, error)
}
EnhancedRecorder starts a collector for a single remote-access session.
func NewPlatformEnhancedRecorder ¶
func NewPlatformEnhancedRecorder() EnhancedRecorder
NewPlatformEnhancedRecorder returns the Linux host-event fallback collector. It reads public procfs surfaces and refuses required BPF policies unless the policy explicitly allows fallback.
type EnhancedRecording ¶
type EnhancedRecording interface {
Events() <-chan EnhancedEvent
Stop(context.Context) error
}
EnhancedRecording is a running collector instance scoped to one session.
type EnhancedRecordingPolicy ¶
type EnhancedRecordingPolicy struct {
Enabled bool `json:"enabled,omitempty"`
Required bool `json:"required,omitempty"`
Mode string `json:"mode,omitempty"`
AllowFallback bool `json:"allow_fallback,omitempty"`
IncludeCommandArguments bool `json:"include_command_arguments,omitempty"`
IncludeFilePaths bool `json:"include_file_paths,omitempty"`
IncludeNetworkAddresses bool `json:"include_network_addresses,omitempty"`
}
EnhancedRecordingPolicy is the agent-visible subset of the platform policy. It controls whether host-event tracing is required before target access opens and which sensitive fields are allowed in emitted events.
type EnhancedRecordingSession ¶
type EnhancedRecordingSession struct {
SessionID string
Protocol string
AgentID string
GatewayID string
Target map[string]string
TargetExecutionMode string
CredentialCustodyMode string
Policy EnhancedRecordingPolicy
}
EnhancedRecordingSession identifies the remote-access session being traced.
type ErrorReason ¶
ErrorReason maps internal errors to user-facing frame reasons.
type FileTransferAckPayload ¶ added in v1.2.60
type FileTransferAckPayload struct {
TransferID string `json:"transfer_id"`
Sequence uint64 `json:"sequence"`
Offset int64 `json:"offset"`
}
FileTransferAckPayload acknowledges receipt or application of a data chunk.
func (FileTransferAckPayload) Validate ¶ added in v1.2.60
func (p FileTransferAckPayload) Validate() error
Validate verifies the chunk acknowledgement schema.
type FileTransferDataPayload ¶ added in v1.2.60
type FileTransferDataPayload struct {
TransferID string `json:"transfer_id"`
Sequence uint64 `json:"sequence"`
Offset int64 `json:"offset"`
Data []byte `json:"data,omitempty"`
EOF bool `json:"eof,omitempty"`
}
FileTransferDataPayload carries a bounded chunk of file bytes. When this struct is JSON-encoded, Data is base64-encoded by encoding/json.
func (FileTransferDataPayload) Validate ¶ added in v1.2.60
func (p FileTransferDataPayload) Validate() error
Validate verifies the chunk data schema.
type FileTransferDirection ¶ added in v1.2.60
type FileTransferDirection string
FileTransferDirection groups operations into read, write, and management buckets for RBAC, approval, quota, and recording policy.
func DirectionForOperation ¶ added in v1.2.60
func DirectionForOperation(operation FileTransferOperation) (FileTransferDirection, error)
DirectionForOperation returns the default RBAC/policy direction for an operation.
func (FileTransferDirection) Valid ¶ added in v1.2.60
func (d FileTransferDirection) Valid() bool
Valid returns true when the direction maps to a file-transfer RBAC group.
type FileTransferEntry ¶ added in v1.2.60
type FileTransferEntry struct {
Name string `json:"name"`
Path string `json:"path,omitempty"`
Size int64 `json:"size"`
Mode string `json:"mode"`
IsDir bool `json:"is_dir"`
ModTime time.Time `json:"mod_time"`
}
FileTransferEntry is safe directory or stat metadata returned by SFTP reads.
type FileTransferErrorPayload ¶ added in v1.2.60
type FileTransferErrorPayload struct {
TransferID string `json:"transfer_id"`
ApprovalID string `json:"approval_id,omitempty"`
Status FileTransferStatus `json:"status"`
Code string `json:"code"`
Message string `json:"message,omitempty"`
RedactedPath string `json:"redacted_path,omitempty"`
PathHash string `json:"path_hash,omitempty"`
}
FileTransferErrorPayload reports a denied, failed, canceled, or quota-exhausted transfer.
type FileTransferOperation ¶ added in v1.2.60
type FileTransferOperation string
FileTransferOperation identifies a policy-gated remote filesystem action.
func (FileTransferOperation) Valid ¶ added in v1.2.60
func (o FileTransferOperation) Valid() bool
Valid returns true when the operation is part of the first SFTP slice.
type FileTransferOutcomePayload ¶ added in v1.2.60
type FileTransferOutcomePayload struct {
TransferID string `json:"transfer_id"`
ApprovalID string `json:"approval_id,omitempty"`
Status FileTransferStatus `json:"status"`
BytesTransferred int64 `json:"bytes_transferred,omitempty"`
FilesTransferred int64 `json:"files_transferred,omitempty"`
SHA256 string `json:"sha256,omitempty"`
RedactedPath string `json:"redacted_path,omitempty"`
PathHash string `json:"path_hash,omitempty"`
FailureReason string `json:"failure_reason,omitempty"`
}
FileTransferOutcomePayload reports the durable outcome metadata for audit and replay.
type FileTransferPolicy ¶ added in v1.2.60
type FileTransferPolicy struct {
AllowedOperations []FileTransferOperation `json:"allowed_operations,omitempty"`
AllowedPathRules []string `json:"allowed_path_rules,omitempty"`
DeniedPathRules []string `json:"denied_path_rules,omitempty"`
RedactedPathRules []string `json:"redacted_path_rules,omitempty"`
SymlinkMode FileTransferSymlinkMode `json:"symlink_mode,omitempty"`
MaxBytes int64 `json:"max_bytes,omitempty"`
MaxFiles int64 `json:"max_files,omitempty"`
RequiresApproval bool `json:"requires_approval,omitempty"`
ContentAuditRetain bool `json:"content_audit_retain,omitempty"`
}
FileTransferPolicy is the policy snapshot the selected agent must enforce before and during target file operations.
type FileTransferPolicyDecision ¶ added in v1.2.60
type FileTransferPolicyDecision struct {
Allowed bool `json:"allowed"`
Status FileTransferStatus `json:"status"`
Reason string `json:"reason,omitempty"`
NormalizedPath string `json:"normalized_path,omitempty"`
RedactedPath string `json:"redacted_path,omitempty"`
PathHash string `json:"path_hash,omitempty"`
ContentAuditRetain bool `json:"content_audit_retain,omitempty"`
}
FileTransferPolicyDecision is safe to persist in audit and replay streams.
func EvaluateFileTransferPolicy ¶ added in v1.2.60
func EvaluateFileTransferPolicy(input FileTransferPolicyInput, policy FileTransferPolicy) (FileTransferPolicyDecision, error)
EvaluateFileTransferPolicy applies the agent-enforced policy gates for a transfer. It does not open files and does not inspect file contents.
type FileTransferPolicyInput ¶ added in v1.2.60
type FileTransferPolicyInput struct {
Request FileTransferRequestPayload
ResolvedPath string
ResolvedDestinationPath string
Bytes int64
Files int64
HasSymlink bool
HasDestinationSymlink bool
RealPathOK bool
DestinationRealPathOK bool
Approved bool
}
FileTransferPolicyInput carries the trusted transfer request plus target filesystem facts observed by the selected agent.
type FileTransferProgressPayload ¶ added in v1.2.60
type FileTransferProgressPayload struct {
TransferID string `json:"transfer_id"`
Status FileTransferStatus `json:"status"`
BytesTransferred int64 `json:"bytes_transferred,omitempty"`
FilesTransferred int64 `json:"files_transferred,omitempty"`
TotalBytes int64 `json:"total_bytes,omitempty"`
RedactedPath string `json:"redacted_path,omitempty"`
PathHash string `json:"path_hash,omitempty"`
}
FileTransferProgressPayload reports transfer lifecycle progress. Payloads must contain counters and redacted/hashable path metadata only, never file contents.
type FileTransferRequestPayload ¶ added in v1.2.60
type FileTransferRequestPayload struct {
Protocol string `json:"protocol,omitempty"`
TransferID string `json:"transfer_id"`
SessionID string `json:"session_id"`
Operation FileTransferOperation `json:"operation"`
Direction FileTransferDirection `json:"direction,omitempty"`
Path string `json:"path"`
DestinationPath string `json:"destination_path,omitempty"`
DisplayName string `json:"display_name,omitempty"`
Policy FileTransferPolicy `json:"policy,omitempty"`
Approved bool `json:"approved,omitempty"`
ApprovalID string `json:"approval_id,omitempty"`
}
FileTransferRequestPayload is the JSON payload carried by FrameTypeFileTransferRequest. Route, agent, gateway, target host, credential, custody, recording, and approval override fields are not accepted from browser intent; the trusted control plane adds the policy snapshot and approval binding that the selected agent must enforce before it opens target file handles.
func (FileTransferRequestPayload) Validate ¶ added in v1.2.60
func (p FileTransferRequestPayload) Validate() error
Validate verifies the bounded client intent schema before route/session context is applied.
type FileTransferResult ¶ added in v1.2.60
type FileTransferResult struct {
Outcome FileTransferOutcomePayload
Entries []FileTransferEntry
}
FileTransferResult returns transfer metadata without file contents.
type FileTransferStatus ¶ added in v1.2.60
type FileTransferStatus string
FileTransferStatus is the stable status vocabulary used by frames, audit, and replay.
type FileTransferSymlinkMode ¶ added in v1.2.60
type FileTransferSymlinkMode string
FileTransferSymlinkMode controls how agent-side policy handles target symlinks.
const ( FileTransferSymlinkDeny FileTransferSymlinkMode = "deny" FileTransferSymlinkFollowInsideRoot FileTransferSymlinkMode = "follow_inside_root" FileTransferSymlinkAllow FileTransferSymlinkMode = "allow" )
func (FileTransferSymlinkMode) Valid ¶ added in v1.2.60
func (m FileTransferSymlinkMode) Valid() bool
Valid returns true for supported symlink modes. Empty defaults to deny.
type Frame ¶
type Frame struct {
SessionID string
Protocol string
FrameType string
Data []byte
Cols uint32
Rows uint32
Reason string
Timestamp int64
Seq uint64
PayloadSHA256 string
Signature string
Metadata map[string]string
}
Frame is the agent-local representation of a remote-access control frame. It intentionally mirrors the OpenSpec frame vocabulary before protobuf compatibility wrappers map it to existing ConsoleFrame traffic.
type FrameAuthenticator ¶ added in v1.2.69
type FrameAuthenticator struct {
// contains filtered or unexported fields
}
FrameAuthenticator signs agent-to-broker frames for a single remote-access session. It is safe for concurrent use by PTY, recording, and transfer loops.
func NewFrameAuthenticatorFromOpenPayload ¶ added in v1.2.69
func NewFrameAuthenticatorFromOpenPayload(data []byte) (*FrameAuthenticator, error)
NewFrameAuthenticatorFromOpenPayload extracts a per-session frame signing key from broker-generated open-frame JSON.
type KnownHostsStore ¶ added in v1.4.95
type KnownHostsStore struct {
// contains filtered or unexported fields
}
KnownHostsStore serializes trust-on-first-use pins into known_hosts files. A pin reads the file and then appends to it, so two sessions pinning at once would each miss the other's line. Every SSH path in the agent that can pin a host key (remote access sessions, file transfers and the Proxmox console) shares one store. The zero value is ready to use.
func (*KnownHostsStore) HostKeyCallback ¶ added in v1.4.95
func (s *KnownHostsStore) HostKeyCallback(policy, knownHostsPath string) (ssh.HostKeyCallback, error)
HostKeyCallback returns the configured host-key verification callback for agent-routed SSH sessions. A nil store refuses trust_on_first_use.
type LinuxProcEnhancedEventSource ¶
type LinuxProcEnhancedEventSource struct {
// contains filtered or unexported fields
}
LinuxProcEnhancedEventSource is a clean-room Linux fallback collector. It polls procfs for process, fd, and socket state and normalizes observations into enhanced-recording events. It is not a BPF collector; required BPF policies must either use a future BPF source or explicitly allow fallback.
func NewLinuxProcEnhancedEventSource ¶
func NewLinuxProcEnhancedEventSource(opts ...LinuxProcOption) *LinuxProcEnhancedEventSource
NewLinuxProcEnhancedEventSource returns a procfs-backed enhanced event source.
func (*LinuxProcEnhancedEventSource) Start ¶
func (source *LinuxProcEnhancedEventSource) Start( ctx context.Context, session EnhancedRecordingSession, ) (<-chan EnhancedEvent, func(context.Context) error, error)
type LinuxProcOption ¶
type LinuxProcOption func(*LinuxProcEnhancedEventSource)
LinuxProcOption configures LinuxProcEnhancedEventSource.
func WithLinuxProcEventBuffer ¶
func WithLinuxProcEventBuffer(size int) LinuxProcOption
WithLinuxProcEventBuffer configures the event channel buffer.
func WithLinuxProcPollInterval ¶
func WithLinuxProcPollInterval(interval time.Duration) LinuxProcOption
WithLinuxProcPollInterval configures the procfs polling interval.
func WithLinuxProcRoot ¶
func WithLinuxProcRoot(path string) LinuxProcOption
WithLinuxProcRoot points the collector at a procfs root. It is primarily for tests.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager routes generic remote-access frames to active adapter sessions.
func NewManager ¶
NewManager creates a remote-access session manager. A nil opener reports ErrAdapterUnavailable for open frames until the caller provides one.
func NewManagerWithConfig ¶
func NewManagerWithConfig(cfg ManagerConfig) *Manager
NewManagerWithConfig creates a remote-access session manager with optional compatibility hooks for callers that are adapting an existing protocol.
type ManagerConfig ¶
type ManagerConfig struct {
Opener Opener
ErrorReason ErrorReason
EnhancedRecorder EnhancedRecorder
}
ManagerConfig configures a remote-access session manager.
type PTY ¶
type PTY interface {
Read(context.Context) ([]byte, error)
Write([]byte) error
Resize(cols, rows uint32) error
Close() error
}
PTY is the byte-oriented terminal interface exposed by terminal protocols.
func OpenSSHFromFrame ¶
OpenSSHFromFrame opens an SSH PTY from a generic remote-access open frame.
type RDPAdapterCapabilities ¶ added in v1.2.69
type RDPAdapterCapabilities struct {
Schema string `json:"schema"`
Protocol string `json:"protocol"`
HelperProtocolVersion int `json:"helper_protocol_version"`
IronRDPBackendLinked bool `json:"ironrdp_backend_linked"`
ConnectorReady bool `json:"connector_ready"`
ConnectorReadyReason string `json:"connector_ready_reason,omitempty"`
}
func ProbeRDPAdapterCapabilities ¶ added in v1.2.69
type RemoteAccessStreamStatus ¶ added in v1.2.67
type RemoteAccessStreamStatus string
RemoteAccessStreamStatus is the status vocabulary shared by app/TCP progress, error, and outcome frames.
func (RemoteAccessStreamStatus) Valid ¶ added in v1.2.67
func (s RemoteAccessStreamStatus) Valid() bool
Valid returns true when the stream status is part of the app/TCP audit vocabulary.
type SFTPAdapter ¶ added in v1.2.60
type SFTPAdapter struct {
Dial SFTPDialer
Policy FileTransferPolicy
Approved bool
MaxChunkBytes int
ChmodMode os.FileMode
ChmodModeSet bool
ChownUID int
ChownGID int
ChownSet bool
KnownHostsPath string
KnownHosts *KnownHostsStore
}
SFTPAdapter executes policy-gated SFTP operations.
func (SFTPAdapter) Execute ¶ added in v1.2.60
func (a SFTPAdapter) Execute( ctx context.Context, cfg SSHConfig, request FileTransferRequestPayload, input io.Reader, output io.Writer, ) (FileTransferResult, error)
Execute runs one SFTP operation. File contents are streamed only through the supplied input/output handles and are not retained by the adapter.
type SFTPClient ¶ added in v1.2.60
type SFTPClient interface {
io.Closer
Chmod(path string, mode os.FileMode) error
Chown(path string, uid int, gid int) error
Create(path string) (SFTPFile, error)
Lstat(path string) (os.FileInfo, error)
Mkdir(path string) error
Open(path string) (SFTPFile, error)
ReadDir(path string) ([]os.FileInfo, error)
RealPath(path string) (string, error)
Remove(path string) error
Rename(oldname string, newname string) error
Stat(path string) (os.FileInfo, error)
}
SFTPClient is the subset of github.com/pkg/sftp.Client used by the adapter.
type SFTPDialer ¶ added in v1.2.60
type SFTPDialer func(context.Context, SSHConfig) (SFTPClient, error)
SFTPDialer opens an SFTP client using session-scoped SSH configuration.
type SSHAuth ¶
type SSHAuth struct {
Username string `json:"username,omitempty"`
Password string `json:"password,omitempty"`
PrivateKey string `json:"private_key,omitempty"`
Passphrase string `json:"passphrase,omitempty"`
Certificate string `json:"certificate,omitempty"`
}
SSHAuth contains session-scoped SSH credentials. Callers must not persist private keys, passwords, or passphrases when using user-present custody.
type SSHConfig ¶
type SSHConfig struct {
Target SSHTarget
Auth SSHAuth
TerminalType string
Cols uint32
Rows uint32
Timeout time.Duration
SSHHostKeyPolicy string
SSHHostKeyApproval *SSHHostKeyApproval
KnownHostsPath string
// KnownHosts serializes trust-on-first-use pins into KnownHostsPath. Nil
// refuses every policy that would pin a key.
KnownHosts *KnownHostsStore
}
SSHConfig configures an SSH-backed PTY adapter.
func SSHConfigFromOpenFrame ¶
SSHConfigFromOpenFrame decodes and validates an SSH open frame.
type SSHDialer ¶
type SSHDialer func(context.Context, SSHConfig) (SSHSession, error)
SSHDialer opens an SSH session for tests or alternate transports.
type SSHHostKeyApproval ¶ added in v1.4.52
type SSHOpenOptions ¶
type SSHOpenOptions struct {
Dial SSHDialer
KnownHostsPath string
KnownHosts *KnownHostsStore
}
SSHOpenOptions configures frame-to-PTY SSH opening.
type SSHOpenPayload ¶
type SSHOpenPayload struct {
Protocol string `json:"protocol,omitempty"`
SessionID string `json:"session_id,omitempty"`
AgentID string `json:"agent_id,omitempty"`
GatewayID string `json:"gateway_id,omitempty"`
Target SSHTarget `json:"target"`
SSH SSHAuth `json:"ssh,omitempty"`
CredentialMode string `json:"credential_mode,omitempty"`
TerminalType string `json:"terminal_type,omitempty"`
TimeoutMS int `json:"timeout_ms,omitempty"`
SSHHostKeyPolicy string `json:"ssh_host_key_policy,omitempty"`
SSHHostKeyApproval *SSHHostKeyApproval `json:"ssh_host_key_approval,omitempty"`
}
SSHOpenPayload is the JSON payload carried by an SSH open frame.
type SSHSession ¶
type SSHSession interface {
StdinPipe() (io.WriteCloser, error)
StdoutPipe() (io.Reader, error)
StderrPipe() (io.Reader, error)
RequestPty(term string, h, w int) error
WindowChange(h, w int) error
Shell() error
Wait() error
Close() error
}
SSHSession is the subset of x/crypto/ssh.Session used by the PTY adapter.
type SourceEnhancedRecorder ¶
type SourceEnhancedRecorder struct {
// contains filtered or unexported fields
}
SourceEnhancedRecorder adapts a collector source to the manager's EnhancedRecorder interface.
func NewSourceEnhancedRecorder ¶
func NewSourceEnhancedRecorder(source EnhancedEventSource) *SourceEnhancedRecorder
NewSourceEnhancedRecorder returns an EnhancedRecorder backed by source.
func (*SourceEnhancedRecorder) Start ¶
func (r *SourceEnhancedRecorder) Start( ctx context.Context, session EnhancedRecordingSession, ) (EnhancedRecording, error)
type TCPAdapter ¶ added in v1.2.67
type TCPAdapter struct {
// contains filtered or unexported fields
}
func NewTCPAdapter ¶ added in v1.2.67
func NewTCPAdapter(ctx context.Context, open TCPOpenPayload, opts TCPAdapterOptions) (*TCPAdapter, error)
func (*TCPAdapter) Close ¶ added in v1.2.67
func (a *TCPAdapter) Close() error
func (*TCPAdapter) Read ¶ added in v1.2.67
func (a *TCPAdapter) Read(ctx context.Context, maxChunkBytes int) (TCPDataPayload, TCPProgressPayload, error)
func (*TCPAdapter) Write ¶ added in v1.2.67
func (a *TCPAdapter) Write(frame TCPDataPayload) (TCPProgressPayload, error)
type TCPAdapterOptions ¶ added in v1.2.67
type TCPAdapterOptions struct {
DialContext TCPDialer
}
type TCPClosePayload ¶ added in v1.2.67
type TCPClosePayload struct {
SessionID string `json:"session_id"`
ConnectionID string `json:"connection_id"`
Reason string `json:"reason,omitempty"`
}
TCPClosePayload reports an orderly TCP connection close.
func (TCPClosePayload) Validate ¶ added in v1.2.67
func (p TCPClosePayload) Validate() error
type TCPDataDirection ¶ added in v1.2.67
type TCPDataDirection string
TCPDataDirection marks whether bounded bytes flow toward the TCP upstream or back toward the client renderer.
func (TCPDataDirection) Valid ¶ added in v1.2.67
func (d TCPDataDirection) Valid() bool
Valid returns true when the TCP data direction is part of the frame contract.
type TCPDataPayload ¶ added in v1.2.67
type TCPDataPayload struct {
SessionID string `json:"session_id"`
ConnectionID string `json:"connection_id"`
Direction TCPDataDirection `json:"direction"`
Sequence uint64 `json:"sequence"`
Data []byte `json:"data,omitempty"`
EOF bool `json:"eof,omitempty"`
}
TCPDataPayload carries one bounded byte chunk for an explicitly registered TCP target.
func (TCPDataPayload) Validate ¶ added in v1.2.67
func (p TCPDataPayload) Validate() error
type TCPErrorPayload ¶ added in v1.2.67
type TCPErrorPayload struct {
SessionID string `json:"session_id"`
ConnectionID string `json:"connection_id,omitempty"`
Status RemoteAccessStreamStatus `json:"status"`
Code string `json:"code"`
Message string `json:"message,omitempty"`
}
TCPErrorPayload reports a denied, failed, or quota-exhausted TCP stream.
func (TCPErrorPayload) Validate ¶ added in v1.2.67
func (p TCPErrorPayload) Validate() error
type TCPOpenPayload ¶ added in v1.2.67
type TCPOpenPayload struct {
TargetID string `json:"target_id"`
SessionID string `json:"session_id"`
ConnectionID string `json:"connection_id"`
UpstreamHost string `json:"upstream_host"`
UpstreamPort int `json:"upstream_port"`
ProtocolName string `json:"protocol_name,omitempty"`
IdleTimeoutSeconds int `json:"idle_timeout_seconds,omitempty"`
AbsoluteTimeoutSeconds int `json:"absolute_timeout_seconds,omitempty"`
QuotaPolicy map[string]any `json:"quota_policy,omitempty"`
ApprovalID string `json:"approval_id,omitempty"`
RecordingPolicy map[string]any `json:"recording_policy,omitempty"`
EnhancedRecordingPolicy map[string]any `json:"enhanced_recording_policy,omitempty"`
Metadata map[string]string `json:"metadata,omitempty"`
}
TCPOpenPayload is carried by FrameTypeTCPOpen after target policy resolution.
func (TCPOpenPayload) Validate ¶ added in v1.2.67
func (p TCPOpenPayload) Validate() error
type TCPOutcomePayload ¶ added in v1.2.67
type TCPOutcomePayload struct {
SessionID string `json:"session_id"`
TargetID string `json:"target_id"`
ConnectionID string `json:"connection_id"`
Status RemoteAccessStreamStatus `json:"status"`
BytesIn int64 `json:"bytes_in,omitempty"`
BytesOut int64 `json:"bytes_out,omitempty"`
FailureReason string `json:"failure_reason,omitempty"`
}
TCPOutcomePayload reports durable TCP metadata for audit and replay.
func (TCPOutcomePayload) Validate ¶ added in v1.2.67
func (p TCPOutcomePayload) Validate() error
type TCPProgressPayload ¶ added in v1.2.67
type TCPProgressPayload struct {
SessionID string `json:"session_id"`
ConnectionID string `json:"connection_id"`
Status RemoteAccessStreamStatus `json:"status"`
BytesIn int64 `json:"bytes_in,omitempty"`
BytesOut int64 `json:"bytes_out,omitempty"`
}
TCPProgressPayload reports TCP connection lifecycle and byte-count metadata.
func (TCPProgressPayload) Validate ¶ added in v1.2.67
func (p TCPProgressPayload) Validate() error
Source Files
¶
- adapters.go
- app_tcp_frames.go
- application_http.go
- desktop.go
- desktop_adapter.go
- desktop_adapter_probe.go
- desktop_audit.go
- desktop_credential.go
- desktop_frame.go
- desktop_media.go
- desktop_media_ack.go
- desktop_media_credit.go
- desktop_media_frame.go
- desktop_session_guard.go
- desktop_target.go
- enhanced_recorder.go
- enhanced_recording.go
- enhanced_recording_ebpf.go
- enhanced_recording_ebpf_loss.go
- enhanced_recording_linux.go
- enhanced_recording_platform_linux.go
- enhanced_recording_sanitize.go
- file_transfer.go
- file_transfer_policy.go
- frame_auth.go
- manager.go
- sftp.go
- ssh.go
- ssh_host_key.go
- ssh_open.go
- tcp_adapter.go