session

Documentation

Index

• Variables
• func ValidatePersistentState(path string, key []byte) error
• type ActiveJob
• type Agent
• type AgentSummary
• type Artifact
• type AuditEvent
• type FailureAlert
• type FleetActivityEvent
• type FleetOverview
• type OverviewAlertState
• type Store
  • func NewPersistentStore(path string) (*Store, error)
  • func NewPersistentStoreWithKey(path string, key []byte) (*Store, error)
  • func NewStore() *Store
  • func (s *Store) AddArtifact(agentID string, artifact Artifact) (Artifact, bool)
  • func (s *Store) AddArtifactChecked(agentID string, artifact Artifact) (Artifact, bool, error)
  • func (s *Store) AuditLog() []AuditEvent
  • func (s *Store) ClearOutputs(agentID string) bool
  • func (s *Store) Close() error
  • func (s *Store) DeleteAgent(agentID string) bool
  • func (s *Store) DeleteArtifact(agentID, artifactID string) bool
  • func (s *Store) DeliverTask(agentID string) *protocol.Task
  • func (s *Store) DequeueTask(agentID string) *protocol.Task
  • func (s *Store) EnqueueTask(agentID string, t *protocol.Task) error
  • func (s *Store) Flush() error
  • func (s *Store) Get(id string) (Agent, bool)
  • func (s *Store) GetArtifact(agentID, artifactID string) (Artifact, bool)
  • func (s *Store) GetOutputs(agentID string) []TaskOutput
  • func (s *Store) GetQueuedTasks(agentID string) []TaskSummary
  • func (s *Store) List() []*Agent
  • func (s *Store) ListArtifacts(agentID string) []Artifact
  • func (s *Store) Overview() FleetOverview
  • func (s *Store) RecordOutput(agentID string, result *protocol.TaskResult) bool
  • func (s *Store) Register(a *Agent)
  • func (s *Store) RekeyAgent(agentID string, secret []byte) bool
  • func (s *Store) RemoveQueuedTask(agentID, taskID string) bool
  • func (s *Store) ResolveFailureAlert(alertID, disposition string) bool
  • func (s *Store) Secret(id string) ([]byte, bool)
  • func (s *Store) SetArtifactRetention(agentID string, limit int) bool
  • func (s *Store) SetRetired(agentID string, retired bool) (Agent, bool)
  • func (s *Store) Subscribe(agentID string) chan struct{}
  • func (s *Store) Unsubscribe(agentID string, ch chan struct{})
  • func (s *Store) UpdateInfo(id, hostname, osName, arch string)
  • func (s *Store) UpdateInfoWithAddresses(id, hostname, osName, arch, transport, sourceIP, hostIP string, ...)
  • func (s *Store) UpdateInfoWithRuntime(id, hostname, osName, arch, transport string, sleepSeconds int)
  • func (s *Store) UpdateInfoWithSource(id, hostname, osName, arch, transport, sourceIP string, sleepSeconds int)
  • func (s *Store) UpdateInfoWithTransport(id, hostname, osName, arch, transport string)
  • func (s *Store) UpdateMetadata(agentID, notes string, tags []string) (Agent, bool)
  • func (s *Store) UpdateMetadataWithName(agentID, displayName, notes string, tags []string) (Agent, bool)
• type TaskOutcomeBucket
• type TaskOutput
• type TaskSummary

Variables

var (
	ErrAgentNotFound = errors.New("agent not found")
	ErrAgentRetired  = errors.New("agent is retired")
	ErrTaskQueueFull = errors.New("task queue full")
)

Functions

func ValidatePersistentState

func ValidatePersistentState(path string, key []byte) error

ValidatePersistentState verifies that an existing state file can be decoded and parsed with key without starting a store or modifying the file.

Types

type ActiveJob

type ActiveJob struct {
	ID         string    `json:"id"`
	AgentID    string    `json:"agent_id"`
	AgentName  string    `json:"agent_name"`
	Type       string    `json:"type"`
	Payload    string    `json:"payload,omitempty"`
	ReceivedAt time.Time `json:"received_at,omitempty"`
}

ActiveJob is work that has been delivered to an agent and has not produced a terminal result yet. Tasks that are still waiting in the operator queue are intentionally excluded.

type Agent

type Agent struct {
	ID                string        `json:"id"`
	Secret            []byte        `json:"-"`
	DisplayName       string        `json:"display_name,omitempty"`
	Hostname          string        `json:"hostname"`
	OS                string        `json:"os"`
	Arch              string        `json:"arch"`
	Transport         string        `json:"transport,omitempty"`
	LastIP            string        `json:"last_ip,omitempty"`
	HostIP            string        `json:"host_ip,omitempty"`
	RegisteredAt      time.Time     `json:"registered_at,omitempty"`
	FirstSeen         time.Time     `json:"first_seen,omitempty"`
	LastSeen          time.Time     `json:"last_seen"`
	SleepSeconds      int           `json:"sleep_seconds,omitempty"`
	Retired           bool          `json:"retired,omitempty"`
	RetiredAt         time.Time     `json:"retired_at,omitempty"`
	Notes             string        `json:"notes,omitempty"`
	Tags              []string      `json:"tags,omitempty"`
	Queued            []TaskSummary `json:"queued,omitempty"`
	Outputs           []TaskOutput  `json:"outputs,omitempty"`
	Artifacts         []Artifact    `json:"artifacts,omitempty"`
	ArtifactRetention int           `json:"artifact_retention,omitempty"`
	Status            string        `json:"status,omitempty"`
	ExpectedNextSeen  time.Time     `json:"expected_next_seen,omitempty"`
	QueuedCount       int           `json:"queued_count"`
	RunningCount      int           `json:"running_count"`
	ActiveTransfers   int           `json:"active_transfers"`
	ArtifactCount     int           `json:"artifact_count"`
	LastResultAt      time.Time     `json:"last_result_at,omitempty"`
	LastResultStatus  string        `json:"last_result_status,omitempty"`
	// contains filtered or unexported fields
}

Agent holds state for a connected implant. Secret is excluded from JSON to prevent it leaking through API responses.

type AgentSummary

type AgentSummary struct {
	ID               string    `json:"id"`
	DisplayName      string    `json:"display_name,omitempty"`
	Hostname         string    `json:"hostname,omitempty"`
	OS               string    `json:"os,omitempty"`
	Arch             string    `json:"arch,omitempty"`
	Transport        string    `json:"transport,omitempty"`
	LastIP           string    `json:"last_ip,omitempty"`
	HostIP           string    `json:"host_ip,omitempty"`
	RegisteredAt     time.Time `json:"registered_at,omitempty"`
	FirstSeen        time.Time `json:"first_seen,omitempty"`
	LastSeen         time.Time `json:"last_seen,omitempty"`
	ExpectedNextSeen time.Time `json:"expected_next_seen,omitempty"`
	SleepSeconds     int       `json:"sleep_seconds,omitempty"`
	Status           string    `json:"status"`
	Retired          bool      `json:"retired,omitempty"`
	RetiredAt        time.Time `json:"retired_at,omitempty"`
	Tags             []string  `json:"tags,omitempty"`
	QueuedCount      int       `json:"queued_count"`
	RunningCount     int       `json:"running_count"`
	ActiveTransfers  int       `json:"active_transfers"`
	ArtifactCount    int       `json:"artifact_count"`
	LastResultAt     time.Time `json:"last_result_at,omitempty"`
	LastResultStatus string    `json:"last_result_status,omitempty"`
}

type Artifact

type Artifact struct {
	ID              string    `json:"id"`
	Key             string    `json:"key,omitempty"`
	TaskID          string    `json:"task_id,omitempty"`
	Type            string    `json:"type,omitempty"`
	Label           string    `json:"label,omitempty"`
	Filename        string    `json:"filename"`
	ArchiveFilename string    `json:"archive_filename,omitempty"`
	MIME            string    `json:"mime,omitempty"`
	Data            string    `json:"data,omitempty"`
	SizeBytes       int64     `json:"size_bytes,omitempty"`
	Compress        bool      `json:"compress,omitempty"`
	CreatedAt       time.Time `json:"created_at"`
}

type AuditEvent

type AuditEvent struct {
	Timestamp time.Time `json:"timestamp"`
	AgentID   string    `json:"agent_id,omitempty"`
	Action    string    `json:"action"`
	Detail    string    `json:"detail,omitempty"`
}

type FailureAlert

type FailureAlert struct {
	ID        string    `json:"id"`
	Timestamp time.Time `json:"timestamp"`
	AgentID   string    `json:"agent_id"`
	AgentName string    `json:"agent_name"`
	TaskID    string    `json:"task_id"`
	TaskType  string    `json:"task_type,omitempty"`
	Detail    string    `json:"detail,omitempty"`
}

type FleetActivityEvent

type FleetActivityEvent struct {
	Timestamp time.Time `json:"timestamp"`
	AgentID   string    `json:"agent_id"`
	AgentName string    `json:"agent_name"`
	Kind      string    `json:"kind"`
	TaskType  string    `json:"task_type,omitempty"`
	Detail    string    `json:"detail,omitempty"`
}

type FleetOverview

type FleetOverview struct {
	GeneratedAt         time.Time            `json:"generated_at"`
	Total               int                  `json:"total"`
	NeverSeen           int                  `json:"never_seen"`
	OnSchedule          int                  `json:"on_schedule"`
	Overdue             int                  `json:"overdue"`
	Offline             int                  `json:"offline"`
	Retired             int                  `json:"retired"`
	QueuedTasks         int                  `json:"queued_tasks"`
	RunningTasks        int                  `json:"running_tasks"`
	ActiveJobs          []ActiveJob          `json:"active_jobs"`
	ActiveTransfers     int                  `json:"active_transfers"`
	FailedLast24Hours   int                  `json:"failed_last_24_hours"`
	Agents              []AgentSummary       `json:"agents"`
	TaskOutcomes24Hours []TaskOutcomeBucket  `json:"task_outcomes_24h"`
	TaskOutcomes7Days   []TaskOutcomeBucket  `json:"task_outcomes_7d"`
	RecentActivity      []FleetActivityEvent `json:"recent_activity"`
	FailureAlerts       []FailureAlert       `json:"failure_alerts"`
}

type OverviewAlertState

type OverviewAlertState struct {
	Disposition string    `json:"disposition"`
	UpdatedAt   time.Time `json:"updated_at"`
}

type Store

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

Store is a concurrency-safe session store.

func NewPersistentStore

func NewPersistentStore(path string) (*Store, error)

NewPersistentStore returns a Store backed by a JSON state file. If path is empty, persistence is disabled and the store behaves like NewStore.

func NewPersistentStoreWithKey

func NewPersistentStoreWithKey(path string, key []byte) (*Store, error)

NewPersistentStoreWithKey returns a JSON state store optionally encrypted with a 32-byte AES-256-GCM key. Existing plaintext state is migrated on the next write when a key is supplied.

func NewStore

func NewStore() *Store

NewStore returns an empty Store.

func (*Store) AddArtifact

func (s *Store) AddArtifact(agentID string, artifact Artifact) (Artifact, bool)

func (*Store) AddArtifactChecked

func (s *Store) AddArtifactChecked(agentID string, artifact Artifact) (Artifact, bool, error)

AddArtifactChecked stores artifact metadata and, for persistent stores, puts the potentially large data body in a separate protected blob file.

func (*Store) AuditLog

func (s *Store) AuditLog() []AuditEvent

func (*Store) ClearOutputs

func (s *Store) ClearOutputs(agentID string) bool

ClearOutputs removes recorded task output history and incomplete output assemblies for an agent. It returns false when the agent does not exist.

func (*Store) Close

func (s *Store) Close() error

Close flushes state and stops the persistence worker. It is idempotent.

func (*Store) DeleteAgent

func (s *Store) DeleteAgent(agentID string) bool

DeleteAgent revokes an agent identity and removes its retained state.

func (*Store) DeleteArtifact

func (s *Store) DeleteArtifact(agentID, artifactID string) bool

DeleteArtifact removes an artifact from an agent's retained library.

func (*Store) DeliverTask

func (s *Store) DeliverTask(agentID string) *protocol.Task

DeliverTask returns the oldest queued task without removing it. It remains in-flight and is retransmitted until RecordOutput observes an acknowledgment.

func (*Store) DequeueTask

func (s *Store) DequeueTask(agentID string) *protocol.Task

DequeueTask pops the next pending task for an agent, or nil if none. Deprecated: beacon listeners should use DeliverTask so delivery is reliable.

func (*Store) EnqueueTask

func (s *Store) EnqueueTask(agentID string, t *protocol.Task) error

EnqueueTask adds a task to an agent's pending queue.

func (*Store) Flush

func (s *Store) Flush() error

Flush waits until the current in-memory state has been written.

func (*Store) Get

func (s *Store) Get(id string) (Agent, bool)

Get returns a value-copy snapshot of the Agent for id. ok is false if not found. Returning a copy (not a pointer) prevents callers from racing with concurrent UpdateInfo/RecordOutput writes after the read lock is released.

func (*Store) GetArtifact

func (s *Store) GetArtifact(agentID, artifactID string) (Artifact, bool)

func (*Store) GetOutputs

func (s *Store) GetOutputs(agentID string) []TaskOutput

GetOutputs returns a copy of the task output history for an agent.

func (*Store) GetQueuedTasks

func (s *Store) GetQueuedTasks(agentID string) []TaskSummary

func (*Store) List

func (s *Store) List() []*Agent

List returns a snapshot of all agents without secrets, task queues, or output history.

func (*Store) ListArtifacts

func (s *Store) ListArtifacts(agentID string) []Artifact

func (*Store) Overview

func (s *Store) Overview() FleetOverview

Overview returns lightweight, fleet-wide status and activity summaries. It intentionally omits output and artifact payload lists so frequent dashboard refreshes remain cheap as the fleet grows.

func (*Store) RecordOutput

func (s *Store) RecordOutput(agentID string, result *protocol.TaskResult) bool

RecordOutput appends a completed task result to the agent's output history and notifies any SSE subscribers. Chunked results are reassembled before they are recorded. It returns false while a chunked result is still incomplete.

func (*Store) Register

func (s *Store) Register(a *Agent)

Register adds or replaces an agent session.

func (*Store) RekeyAgent

func (s *Store) RekeyAgent(agentID string, secret []byte) bool

RekeyAgent replaces an agent's pre-shared secret while retaining its history.

func (*Store) RemoveQueuedTask

func (s *Store) RemoveQueuedTask(agentID, taskID string) bool

func (*Store) ResolveFailureAlert

func (s *Store) ResolveFailureAlert(alertID, disposition string) bool

ResolveFailureAlert removes one failure from Overview attention and counters without mutating the agent's retained task output or historical outcome data.

func (*Store) Secret

func (s *Store) Secret(id string) ([]byte, bool)

Secret returns only the pre-shared secret for an agent. Avoids exposing the full Agent struct when only the secret is needed.

func (*Store) SetArtifactRetention

func (s *Store) SetArtifactRetention(agentID string, limit int) bool

SetArtifactRetention changes the retained artifact count for one agent and immediately removes the oldest excess entries.

func (*Store) SetRetired

func (s *Store) SetRetired(agentID string, retired bool) (Agent, bool)

func (*Store) Subscribe

func (s *Store) Subscribe(agentID string) chan struct{}

Subscribe registers a buffered channel that receives a signal each time a new output is recorded for agentID. The caller must call Unsubscribe when done.

func (*Store) Unsubscribe

func (s *Store) Unsubscribe(agentID string, ch chan struct{})

Unsubscribe removes a channel previously registered via Subscribe.

func (*Store) UpdateInfo

func (s *Store) UpdateInfo(id, hostname, osName, arch string)

UpdateInfo updates hostname, OS, arch, and last-seen from a beacon. Replaces the old Touch-only pattern so beacon metadata is kept current.

func (*Store) UpdateInfoWithAddresses

func (s *Store) UpdateInfoWithAddresses(id, hostname, osName, arch, transport, sourceIP, hostIP string, sleepSeconds int)

UpdateInfoWithAddresses records both the server-observed network source and the route-selected local address reported by the authenticated agent.

func (*Store) UpdateInfoWithRuntime

func (s *Store) UpdateInfoWithRuntime(id, hostname, osName, arch, transport string, sleepSeconds int)

UpdateInfoWithRuntime updates beacon metadata, including the agent's current configured sleep interval. Older agents may report zero; in that case the last known interval is preserved.

func (*Store) UpdateInfoWithSource

func (s *Store) UpdateInfoWithSource(id, hostname, osName, arch, transport, sourceIP string, sleepSeconds int)

UpdateInfoWithSource updates beacon metadata and records the authenticated network source used for the most recent check-in.

func (*Store) UpdateInfoWithTransport

func (s *Store) UpdateInfoWithTransport(id, hostname, osName, arch, transport string)

UpdateInfoWithTransport updates beacon metadata including the transport used for the most recent check-in.

func (*Store) UpdateMetadata

func (s *Store) UpdateMetadata(agentID, notes string, tags []string) (Agent, bool)

func (*Store) UpdateMetadataWithName

func (s *Store) UpdateMetadataWithName(agentID, displayName, notes string, tags []string) (Agent, bool)

type TaskOutcomeBucket

type TaskOutcomeBucket struct {
	Start      time.Time `json:"start"`
	Successful int       `json:"successful"`
	Warnings   int       `json:"warnings"`
	Failed     int       `json:"failed"`
}

type TaskOutput

type TaskOutput struct {
	TaskID          string    `json:"task_id"`
	Type            string    `json:"type"`
	Payload         string    `json:"payload,omitempty"`
	Output          string    `json:"output"`
	Warning         string    `json:"warning,omitempty"`
	Error           string    `json:"error,omitempty"`
	QueuedAt        time.Time `json:"queued_at,omitempty"`
	LastDeliveredAt time.Time `json:"last_delivered_at,omitempty"`
	Timestamp       time.Time `json:"timestamp"`
}

TaskOutput records the result of a completed task for the audit trail.

type TaskSummary

type TaskSummary struct {
	ID               string    `json:"id"`
	Type             string    `json:"type"`
	Payload          string    `json:"payload,omitempty"`
	Status           string    `json:"status"`
	DeliveryAttempts int       `json:"delivery_attempts,omitempty"`
	QueuedAt         time.Time `json:"queued_at"`
	LastDeliveredAt  time.Time `json:"last_delivered_at,omitempty"`
}