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
- Variables
- func CheckKinds(p config.Profile) error
- type AgentRuleStatus
- type Confinement
- type Field
- type Options
- type Session
- func (s *Session) AddAgentRule(canonical string) (*logconsole.Refusal, error)
- func (s *Session) CheckAgentRule(pattern string) (string, *logconsole.Refusal)
- func (s *Session) Close() error
- func (s *Session) Exposed(result any) (string, []logconsole.ExposedRecord)
- func (s *Session) Handle(ctx context.Context, method string, params json.RawMessage, ...) (any, *logconsole.Refusal, error)
- func (s *Session) PIIRules() (maskRules, allow []string)
- func (s *Session) Reveal(ctx context.Context, result any) []string
- func (s *Session) Status(ctx context.Context) any
- type SourceInfo
- type SourceStatus
- type Sources
- type Status
Constants ¶
const IndexBytesPerHour = 20 << 30
IndexBytesPerHour is the local index building budget (design §3.3).
Variables ¶
var Supported = []string{config.KindFile, config.KindJournald, config.KindDocker, config.KindLoki, config.KindElastic, config.KindOpenSearch}
Supported are the source kinds this build reads.
Functions ¶
func CheckKinds ¶
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 ¶
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 (*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 ¶
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
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.
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.