Documentation
¶
Overview ¶
Package allowlist holds the values that may change on every request (time, tokens). Their value is not compared, but their format still is, and every entry carries a reason.
Index ¶
- Constants
- func IsCellPath(path string) bool
- func SameParts(rules []*BodyRule, base, cur string) bool
- type ArrayRule
- type BodyRule
- type Finding
- type HeaderRule
- type List
- func (l *List) AnyLength(request, path string) bool
- func (l *List) ArrayKey(request, path string) *ArrayRule
- func (l *List) CellRules(request, path string) (*BodyRule, []*BodyRule)
- func (l *List) Copy() *List
- func (l *List) Done(request string, values, bodies bool)
- func (l *List) ForRequest(request string) *List
- func (l *List) ForTarget(target string) *List
- func (l *List) HasCellRules() bool
- func (l *List) HasRawRule(request string) bool
- func (l *List) Header(name string) *HeaderRule
- func (l *List) HeaderFor(request, name string) *HeaderRule
- func (l *List) Lint() []Finding
- func (l *List) Marshal() ([]byte, error)
- func (l *List) RawRule(request string) *BodyRule
- func (l *List) TextRules(request, path string) (*BodyRule, []*BodyRule)
- func (l *List) Track() *List
- func (l *List) Unused(selected bool) []Unused
- func (l *List) Validate() error
- func (l *List) ValueRules(request, path string) (*BodyRule, []*BodyRule)
- type RuleRef
- type Unused
- type Usage
Constants ¶
const ( CheckNoRequest = "no-request" // the rule applies to no compared request CheckNoPlace = "no-place" // it reaches nothing in the baseline bodies of its requests CheckAnyLength = "any-length-values" // any_length without format whose glob reaches values CheckRawRequest = "raw-without-request" // a $raw rule for every request CheckBroad = "broad" // see broad CheckShadowed = "shadowed" // an earlier rule always decides first CheckDuplicate = "duplicate" // the same rule again )
Checks of driftgate allowlist check: what a rule does that its author probably did not mean. Lint finds those that need only the list; the command adds those that need the catalog and a baseline.
const RawPath = "$raw"
RawPath is the path of a body rule for the whole body: when the bytes of a body that is not JSON differ, the current body as text must match the format, and then it is not compared further. It is taken literally, not as a glob, so a wildcard path never stands for the whole body.
const Version = 1
Variables ¶
This section is empty.
Functions ¶
func IsCellPath ¶
IsCellPath reports whether a rule's path names cells of a spreadsheet: it starts with xlsx: or csv!. Only such rules apply to cells; a path that starts with a wildcard (*) stays with JSON and HTML, as before cells had rules.
func SameParts ¶
SameParts reports whether two values are the same once every part a rule with parts matches is set aside. Each value is cut into literal pieces and matched parts (rule by rule, a later rule only within the literal pieces an earlier one left); the literal pieces must be equal, and a matched part stands for any text the rule matches.
Types ¶
type ArrayRule ¶
type ArrayRule struct {
Target string `yaml:"target,omitempty"`
Request string `yaml:"request,omitempty"`
Path string `yaml:"path"` // glob over JSON paths of arrays
Key string `yaml:"key"` // a member of every item, or a path into it (user.id)
AnyOrder bool `yaml:"any_order,omitempty"`
Reason string `yaml:"reason"`
// contains filtered or unexported fields
}
ArrayRule pairs the items of a JSON array by a key instead of by position: an item inserted at the front is one new item, not a change of every item after it. Items that are new or gone are drifts (unless an any_length rule lets the array change length), and so is a changed order of the items both sides have, unless AnyOrder.
type BodyRule ¶
type BodyRule struct {
Target string `yaml:"target,omitempty"` // only requests of this service
Request string `yaml:"request,omitempty"` // glob over request IDs; empty means all
Path string `yaml:"path"` // glob over body paths
Format string `yaml:"format,omitempty"`
AnyLength bool `yaml:"any_length,omitempty"` // arrays at this path may change length; values need a format
// Parts: the format matches parts of the value (a hash in an asset URL, a
// build id inside a script); only those parts may change, the rest of
// the value is still compared. Without it the format matches the whole
// value.
Parts bool `yaml:"parts,omitempty"`
Reason string `yaml:"reason"`
// contains filtered or unexported fields
}
BodyRule allows a value inside a body to change while it keeps its format. The path is a JSON path ($.token), a path in an HTML page (html>body>p@class, html>body>script#__NEXT_DATA__$.buildId) or in its RSC payload (self.__next_f$.0.b), a cell of a spreadsheet (xlsx:Users!A1, csv!A1), or a glob over them. The path RawPath names the whole body of a response that is not JSON (see RawRule).
func (*BodyRule) Matches ¶
Matches reports whether a value keeps the rule's format; a rule without a format (any_length) matches no value.
type HeaderRule ¶
type HeaderRule struct {
Target string `yaml:"target,omitempty"` // only requests of this service
Request string `yaml:"request,omitempty"` // glob over request IDs; empty means all
Name string `yaml:"name"`
Format string `yaml:"format,omitempty"`
IgnoreCase bool `yaml:"ignore_case,omitempty"`
Reason string `yaml:"reason"`
// contains filtered or unexported fields
}
HeaderRule allows a header's value to change while it keeps its format, or, with IgnoreCase, only in letter case (charset and media type names are case-insensitive, RFC 9110).
func (*HeaderRule) Matches ¶
func (r *HeaderRule) Matches(value string) bool
Matches reports whether a header value keeps the rule's format.
type List ¶
type List struct {
Version int `yaml:"version"`
Headers []HeaderRule `yaml:"headers"`
Body []BodyRule `yaml:"body"`
Arrays []ArrayRule `yaml:"arrays,omitempty"`
// contains filtered or unexported fields
}
List is the parsed allow-list file.
func (*List) AnyLength ¶
AnyLength reports whether a rule with any_length lets the JSON array at a body path of a request change its length (asked for an array that did).
func (*List) ArrayKey ¶
ArrayKey returns the first array rule that applies to the JSON array at a body path of a request, or nil: its items are then paired by key.
func (*List) CellRules ¶
CellRules is ValueRules for a cell of a spreadsheet: only rules whose path names cells (IsCellPath) apply to them.
func (*List) Done ¶
Done adds what the rules of a list for one request did to the Usage of the list it was made from. values is whether the comparison went as far as values (where header and value rules apply), bodies whether the request's bodies were compared (not when a private body is not on this machine): a rule that had no chance is not counted for the request.
func (*List) ForRequest ¶
ForRequest is the list of rules that can apply to one request: the body rules for other requests are left out once, instead of being matched against the request at every value of its body, and the rest are sorted by kind. The list is the request's own: it counts which rules applied to a change (Done).
func (*List) ForTarget ¶
ForTarget is the list of rules that apply to requests of one service: the rules of that service and the rules that name none.
func (*List) HasCellRules ¶
HasCellRules reports whether a rule can apply to cells of a spreadsheet: a body rule whose path starts with xlsx: or csv! (IsCellPath).
func (*List) HasRawRule ¶
HasRawRule reports whether a whole-body rule applies to the request, without counting it as used.
func (*List) Header ¶
func (l *List) Header(name string) *HeaderRule
Header returns the first rule for a header name (case-insensitive) that applies to every request.
func (*List) HeaderFor ¶
func (l *List) HeaderFor(request, name string) *HeaderRule
HeaderFor returns the first rule for a header name that applies to the request: a rule without request applies to all. In a list for one request the rule counts as used (Track).
func (*List) Lint ¶
Lint checks the rules of a list by themselves: a $raw rule without request, rules that reach far more than a value (broad), and rules that never decide because an earlier one always does (shadowed, duplicate).
func (*List) RawRule ¶
RawRule returns the first whole-body rule (path RawPath) that applies to the request, or nil. The caller asks only when the rule would apply (no body is JSON): in a list for one request it then counts as used.
func (*List) Track ¶
Track returns the list with a new Usage and its rules numbered: lists made from it (ForTarget, ForRequest) count into it.
func (*List) Unused ¶
Unused lists the rules of a tracked list (Track) that applied to no change in the comparison; with selected, only those that apply to a compared request (a comparison of some requests says nothing about the rules of the others).
func (*List) ValueRules ¶
ValueRules returns the rules for a value (a JSON scalar, a text or an attribute of an HTML page) at a body path of a request: the first matching rule with a whole-value format, which then decides alone, and otherwise every matching rule with parts. A rule without a format (any_length) is about the length of JSON arrays and says nothing about a value, so it is passed over. The caller asks for a value that changed: in a list for one request the rules returned count as used.
type RuleRef ¶
type RuleRef struct {
Kind string `json:"kind"` // header, body or array
Rule int `json:"rule"` // its position among the rules of its kind, from 1
Name string `json:"name,omitempty"`
Path string `json:"path,omitempty"`
Request string `json:"request,omitempty"`
Target string `json:"target,omitempty"`
}
RuleRef names a rule of the list in a report: its kind, its position and what it is about.
type Unused ¶
type Unused struct {
RuleRef
// Why: "no request" (it applies to none of the compared requests) or
// "no change" (nothing it applies to changed).
Why string `json:"why"`
}
Unused is a rule that did nothing in a comparison.
type Usage ¶
type Usage struct {
// contains filtered or unexported fields
}
Usage counts, over one comparison, the compared requests every rule applies to and those where it applied to a change. Requests are compared in parallel; each counts in its own list (ForRequest) and adds once, at the end (Done).
Source Files