session

package
v0.2.1 Latest Latest
Warning

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

Go to latest
Published: Nov 7, 2026 License: Apache-2.0 Imports: 37 Imported by: 0

Documentation

Overview

Package session opens the log engine of an approved policy for the console (logconsole.Opener): the masker of each source, the local index in the console's state directory, the sources the policy names (given only the mount roots the launcher checked), the keys (K_ref, pseudonym epochs), the cost model and the budgets, and serves the agent's methods over it.

Everything it returns to the console is masked: records and counts by the engine, source descriptions here (field names the masker would show masked are left out, trusted values go through the masker).

Index

Constants

View Source
const IndexBytesPerHour = 20 << 30

IndexBytesPerHour is the local index building budget (design §3.3).

Variables

Supported are the source kinds this build reads.

Functions

func CheckKinds

func CheckKinds(p config.Profile) error

CheckKinds refuses a profile with a source kind this build does not read: before the console confines itself or opens anything.

Types

type AgentRuleStatus added in v0.2.0

type AgentRuleStatus struct {
	Rules        int        `json:"rules"`
	AddsLastHour int        `json:"adds_last_hour"`
	LastAdd      *time.Time `json:"last_add,omitempty"`
}

AgentRuleStatus counts the agent's masking rules: in all, added in the last hour, and the last one's time.

type Confinement

type Confinement struct {
	Landlock landlock.Status
	Openat2  bool
}

Confinement is how the console confined itself before opening any source (landlock.Restrict) and whether openat2 with RESOLVE_NO_XDEV works: the two guards of the docker source.

type Field

type Field struct {
	Name    string   `json:"name"`
	Label   bool     `json:"label,omitempty"`
	Trusted bool     `json:"trusted,omitempty"`
	Values  []string `json:"values,omitempty"`
}

Field is one field of a source.

type Options

type Options struct {
	logconsole.OpenOptions
	Confinement Confinement
	// FirstOpen is set on the first open of the console's process: a
	// profile with pseudonym_rotation = "session" starts a new epoch then
	// (not when the console reconnects).
	FirstOpen bool
	// EpochsOpened, when set, is called synchronously, before Open
	// returns, once the epoch store is open (and rotated, on a first open): an open that fails after it has used up
	// the first open's rotation, so the caller stops passing FirstOpen.
	EpochsOpened func()
	// Workers mask in parallel (default min(2, NumCPU): the launcher runs
	// the console with --cpus min(2, nproc)).
	Workers int
	Now     func() time.Time
	// Cost replaces the calibrated cost model (tests).
	Cost *engine.CostModel
	// MapDir replaces the docker source's map directory (tests).
	MapDir string
	// Egress tunes the remote sources' clients (tests: timeouts).
	Egress egress.Options
}

Options open a session.

type Session

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

Session is an open engine. It implements logconsole.Engine.

func Open

func Open(ctx context.Context, o Options) (_ *Session, err error)

Open opens the engine of o.Policy.

func (*Session) AddAgentRule added in v0.2.0

func (s *Session) AddAgentRule(canonical string) (*logconsole.Refusal, error)

AddAgentRule implements logconsole.AgentRuler.

func (*Session) CheckAgentRule added in v0.2.0

func (s *Session) CheckAgentRule(pattern string) (string, *logconsole.Refusal)

CheckAgentRule implements logconsole.AgentRuler.

func (*Session) Close

func (s *Session) Close() error

Close stops the indexer, saves the index, releases the epoch store and closes the remote sources' connections.

func (*Session) Exposed added in v0.2.0

func (s *Session) Exposed(result any) (string, []logconsole.ExposedRecord)

Exposed implements logconsole.Exposer: each record of an agent call's result (search, trace, context, tail, an approved scan's page) by its key and the pseudonyms it showed the agent, and their epoch.

func (*Session) Handle

func (s *Session) Handle(ctx context.Context, method string, params json.RawMessage, c logconsole.Caller) (any, *logconsole.Refusal, error)

Handle implements logconsole.Engine.

func (*Session) PIIRules added in v0.2.0

func (s *Session) PIIRules() (maskRules, allow []string)

PIIRules implements logconsole.AgentRuler: the rules in force, masked as any text the agent gets. An agent rule is listed by its mode and when it was added: its field is known by a keyed digest only.

func (*Session) Reveal

func (s *Session) Reveal(ctx context.Context, result any) []string

Reveal implements logconsole.Revealer: the records of an agent call's result (search, trace, context, tail, an approved scan's page), in clear for the console's terminal. Results without records show nothing.

func (*Session) Status

func (s *Session) Status(ctx context.Context) any

Status implements logconsole.Engine.

type SourceInfo

type SourceInfo struct {
	Name    string `json:"name"`
	Kind    string `json:"kind"`
	Format  string `json:"format,omitempty"`
	Streams int    `json:"streams"`
	Bytes   int64  `json:"bytes"`
	// Oldest and Newest bound the records, when known.
	Oldest      *time.Time `json:"oldest,omitempty"`
	Newest      *time.Time `json:"newest,omitempty"`
	IndexedFrom *time.Time `json:"indexed_from,omitempty"`
	Fields      []Field    `json:"fields"`
	// MaskedFields counts the field names left out: the masker shows them
	// masked (⟦key:ID⟧), as the records do.
	MaskedFields int `json:"masked_fields,omitempty"`
	// Error is set when the source could not be described (no detail:
	// its error may name files).
	Error string `json:"error,omitempty"`
}

SourceInfo is one source of log.sources, masked.

type SourceStatus

type SourceStatus struct {
	Name string `json:"name"`
	Kind string `json:"kind"`
	// Containers is a docker source's containers map: its state, the
	// containers served and the stale ones (removed, still mapped).
	Containers *docker.ContainersStatus `json:"containers,omitempty"`
}

SourceStatus names one source.

type Sources

type Sources struct {
	Epoch   string       `json:"epoch"`
	Sources []SourceInfo `json:"sources"`
}

Sources is the answer of log.sources.

type Status

type Status struct {
	Epoch   string         `json:"epoch"`
	Sources []SourceStatus `json:"sources"`
	// Landlock is the console's confinement ("landlock enforced (ABI 5)").
	Landlock string `json:"landlock"`
	// Residuals name the docker source's missing guards.
	Residuals []string `json:"residuals,omitempty"`
	Notes     []string `json:"notes,omitempty"`
	// AgentRules counts the agent's masking rules (pii.add).
	AgentRules AgentRuleStatus `json:"agent_rules"`
	// Budgets is what is left of the rolling budgets.
	Budgets engine.BudgetStatus `json:"budgets"`
}

Status is the engine's part of log.status and :status: no log content.

Jump to

Keyboard shortcuts

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