Documentation
¶
Overview ¶
Package settings is the tool settings contract: what a scan tool lets an administrator configure, declared as a small JSON Schema in the "config" of its tool manifest, and the layered values a scan runs with.
The schema language is a closed subset of JSON Schema 2020-12 plus x-octm-* annotations. Anything outside the subset makes the schema invalid, so a schema cannot hide a field behind $ref, oneOf or a conditional. The platform validates what an administrator enters with this package and the sensor validates it again before a task uses it; both import the same code, so the two can never disagree.
Annotations:
- x-octm-scope ("sensor" | "scan"): the lowest layer allowed to set the key;
- x-octm-tier ("T0" | "T1" | "T2"): the safety class of a non-default value: T0 safe, T1 impact (more load or reach on the target), T2 dangerous (intrusive; needs the tenant's explicit enablement and a T2 scan);
- x-octm-common: the property is one of the common tool options of package tooloption (its type and bounds are checked against it); a property named like a common option must declare it;
- x-octm-flag: the tool's native flag the value maps to ("-rate-limit"), shown in the effective configuration of a job; the tool's adapter still builds the argv itself, from typed values;
- x-octm-sensitive, x-octm-restart, x-octm-group, x-octm-order, x-octm-widget: presentation and handling.
Layers (Resolve): the tool's defaults, then the sensor's configuration, then a scan profile or workflow step, then the scan, then the platform's decision for one job. For a common option that narrows down (rate, concurrency, retries), a later layer may only lower what an earlier layer set; a raise is an error, never silently applied.
The test vectors in testdata/vectors pin the verdicts, error paths, defaults and digests.
Index ¶
- Constants
- func DocumentDigest(raw []byte) (string, error)
- func ValidName(name string) bool
- type Error
- type Errors
- type Layer
- type Property
- type Schema
- type SchemaError
- type Scope
- type Source
- type Values
- func (t *Values) Bool(key string) (bool, bool)
- func (t *Values) Duration(key string) (time.Duration, bool)
- func (t *Values) Float(key string) (float64, bool)
- func (t *Values) Int(key string) (int64, bool)
- func (t *Values) Keys() []string
- func (t *Values) SchemaDigest() string
- func (t *Values) SchemaVersion() int
- func (t *Values) Secret(string) ([]byte, bool)
- func (t *Values) Source(key string) Source
- func (t *Values) String(key string) (string, bool)
- func (t *Values) Strings(key string) ([]string, bool)
- func (t *Values) Values() map[string]any
Constants ¶
const ( // MaxSchemaBytes bounds a schema document. MaxSchemaBytes = 32 << 10 // MaxProperties bounds the properties of a schema, nested ones // included. MaxProperties = 64 // MaxEnum bounds an enum. MaxEnum = 256 // MaxPatternLen bounds a pattern's length. MaxPatternLen = 512 // MaxStringLen bounds any string value (a maxLength, when set, // may only lower it). MaxStringLen = 4096 // MaxItems bounds any array value (a maxItems, when set, may // only lower it). MaxItems = 256 )
Limits of a settings schema.
Variables ¶
This section is empty.
Functions ¶
func DocumentDigest ¶
DocumentDigest is the canonical digest of any JSON document (a values document, a settings document): "sha256:" + hex SHA-256 of its canonical JSON, as for Schema.Digest.
Types ¶
type Error ¶
Error is one invalid value. Path is a JSON pointer into the values document ("/rate_limit", "/group/key", "/tags/2").
type Property ¶
type Property struct {
Name string
Title string
Description string
// Type is "boolean", "integer", "number", "string", "array" or
// "object" (a group of keys, one level deep); empty for a key that only
// has enum or const.
Type string
// Items describes an array's elements.
Items *Property
// Properties are a group's keys, sorted by name.
Properties []*Property
Required []string
Enum []any
Const any
HasConst bool
Default any
HasDefault bool
Minimum, Maximum *float64
ExclusiveMinimum, ExclusiveMaximum *float64
MultipleOf *float64
MinLength, MaxLength *int
MinItems, MaxItems *int
UniqueItems bool
Pattern string
Format string
Deprecated bool
WriteOnly bool
Scope Scope
// Tier is the minimum tier whose policy permits a non-default value
// ("T0", "T1", "T2"); empty: any tier.
Tier string
Sensitive bool
Restart bool
Group string
Order int
Widget string
// Common is the common tool option (package tooloption) the key is,
// "" for a key specific to the tool. Top-level keys only.
Common string
// Flag is the tool's native flag the value maps to ("-rate-limit"):
// shown in a job's effective configuration, never used to build argv.
Flag string
// contains filtered or unexported fields
}
Property is one key of a schema.
type Schema ¶
type Schema struct {
// Raw is the schema document as declared.
Raw json.RawMessage
// Version is x-octm-schema-version: it increases when a key is removed
// or narrowed.
Version int
// Title and Description describe the tool's settings.
Title string
Description string
// Properties are the top-level keys, sorted by name.
Properties []*Property
// Required are the keys that must have a value (given or default).
Required []string
// contains filtered or unexported fields
}
Schema is a tool's parsed settings schema.
func MustParseSchema ¶
MustParseSchema is ParseSchema for a schema compiled into the program; it panics on an invalid one (a programming error).
func ParseSchema ¶
ParseSchema parses and checks a schema: the allowed keywords only, additionalProperties false on every object, one level of grouping, defaults and enums that satisfy their own constraints, RE2 patterns, and the size limits.
func (*Schema) Defaults ¶
Defaults returns every key that has a default, groups as nested objects. The map is the caller's.
func (*Schema) Digest ¶
Digest is "sha256:" + the hex SHA-256 of the schema's canonical JSON (object members sorted, no insignificant whitespace, numbers as written, no HTML escaping). The manifest carries it; the platform stores schemas by it.
func (*Schema) Resolve ¶
Resolve computes the effective settings: the defaults, then each layer in order (sensor, then profile, then scan). Each layer must be valid on its own, and a profile or scan layer may set only keys whose scope is "scan". A nil schema gives empty settings (the tool's own defaults).
func (*Schema) Validate ¶
Validate checks a values document: every key known, every value of the right type and within its constraints, sensitive keys absent (secrets never travel as plain values), and every required key given or defaulted. The error is Errors with every problem.
func (*Schema) ValidateJSON ¶
ValidateJSON is Validate for a JSON object (numbers kept exact).
type SchemaError ¶
SchemaError is why a schema is invalid. Path is a JSON pointer into the schema document.
func (*SchemaError) Error ¶
func (e *SchemaError) Error() string
type Source ¶
type Source string
Source is where an effective value came from.
const ( SourceDefault Source = "default" // SourceTenant: the tenant's policy for every sensor. SourceTenant Source = "tenant" SourceSensor Source = "sensor" SourceProfile Source = "profile" SourceScan Source = "scan" // SourceJob: the platform's decision for one job (learned budgets). SourceJob Source = "job" // SourceLocal: the sensor's local policy, applied last; it only ever // lowers a value (its host owner's caps). SourceLocal Source = "local" )
Setting sources, from lowest to highest precedence.
type Values ¶
type Values struct {
// contains filtered or unexported fields
}
Values are a tool's effective settings for one scan. A nil *Values has no values: every getter reports false and the tool uses its own defaults. Keys of a group are addressed as "group.key".
func (*Values) SchemaDigest ¶
SchemaDigest and SchemaVersion identify the schema the settings were resolved against.
func (*Values) SchemaVersion ¶
SchemaVersion is the schema's x-octm-schema-version.
func (*Values) Secret ¶
Secret returns a sensitive value. Secret settings are not delivered yet, so it always reports false; a tool that asks for one keeps working when they are.
Source Files