Documentation
¶
Overview ¶
Package accesschk parses the text output of the Sysinternals AccessChk tool (https://learn.microsoft.com/en-us/sysinternals/downloads/accesschk) into a structured representation. AccessChk has no machine-readable output mode, so the parser is intentionally tolerant: anything it cannot recognize is preserved verbatim and, for inputs below RawRetentionLimit, the full original text is retained in Raw so a policy can fall back to string matching regardless of the output mode used.
Parse reads from an io.Reader and streams the input line by line rather than buffering the whole material in memory or building a normalized full-text copy, and it size-gates the verbatim fallback fields (Raw and the per-object RawLines). Together these keep peak memory bounded: a large material would otherwise pin multiple copies of itself in memory and inflate the JSON document handed to the policy engine to multiples of the input size.
Index ¶
Constants ¶
const RawRetentionLimit = 10 * 1024 * 1024 // 10 MiB
RawRetentionLimit is the maximum input size (in bytes) for which Parse retains the verbatim fallback fields Raw and RawLines. Above it these fields are omitted: they are not part of the attestation (only the original file's digest is attested) and no policy reads them, so trimming them for oversized inputs does not change the recorded evidence or any current evaluation — it only prevents the transient JSON projection handed to the policy engine from ballooning to multiples of the original file size.
const ToolName = "AccessChk"
ToolName is the canonical tool name recorded for AccessChk materials.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ACE ¶
type ACE struct {
Index int `json:"index"`
AceType string `json:"ace_type,omitempty"`
Principal string `json:"principal"`
AceFlags []string `json:"ace_flags"`
Rights []string `json:"rights"`
}
ACE is a single access control entry from a security descriptor reported by the -l output mode (DACL or SACL).
type AccessEntry ¶
type AccessEntry struct {
Access string `json:"access"`
Principal string `json:"principal"`
Rights []string `json:"rights"`
}
AccessEntry is a single principal and the access it was granted on an object, as reported by the compact default (R/W) output mode.
type Descriptor ¶ added in v1.106.2
type Descriptor struct {
DescriptorFlags []string `json:"descriptor_flags,omitempty"`
Owner string `json:"owner,omitempty"`
DACL []ACE `json:"dacl,omitempty"`
SACL []ACE `json:"sacl,omitempty"`
AccessEntries []AccessEntry `json:"access_entries"`
}
Descriptor is the security-descriptor portion of an Object: the fields that are shared between objects with identical access control. The object name and the verbatim raw lines are intentionally excluded — they belong to the object, not the descriptor.
type Object ¶
type Object struct {
Name string `json:"name"`
DescriptorFlags []string `json:"descriptor_flags,omitempty"`
Owner string `json:"owner,omitempty"`
DACL []ACE `json:"dacl,omitempty"`
SACL []ACE `json:"sacl,omitempty"`
AccessEntries []AccessEntry `json:"access_entries"`
RawLines []string `json:"raw_lines"`
}
Object is a single securable object reported by AccessChk.
AccessEntries is populated by the compact default mode; DescriptorFlags, Owner, DACL and SACL are populated by the -l (full security descriptor) mode. RawLines always holds every indented line verbatim regardless of mode.
type ProjectedObject ¶ added in v1.106.2
type ProjectedObject struct {
Name string `json:"name"`
Descriptor int `json:"descriptor"`
RawLines []string `json:"raw_lines,omitempty"`
}
ProjectedObject is a securable object in the de-duplicated projection: its name and an index into Projection.Descriptors, plus the verbatim RawLines fallback when retained (omitted for oversized inputs, matching Report).
type Projection ¶ added in v1.106.2
type Projection struct {
Tool Tool `json:"tool"`
Descriptors []Descriptor `json:"descriptors"`
Objects []ProjectedObject `json:"objects"`
// Raw holds the full original text for inputs below RawRetentionLimit and is
// empty otherwise, mirroring Report.Raw. It is a string-matching fallback and
// is not read by current policies.
Raw string `json:"raw"`
}
Projection is the JSON structure handed to the policy engine at evaluation time. It carries exactly the same information as a Report, but the security descriptors are de-duplicated: every distinct descriptor (the access-control portion of an object) is listed once in Descriptors, and each object references one by index. AccessChk evidence for a registry hive or a service database applies a handful of distinct descriptors to hundreds of thousands of objects through inheritance, so the flat form repeats the same DACL/ACE structures over and over. De-duplicating makes the projection — and the value the policy engine materialises from it — proportional to the number of DISTINCT descriptors rather than the number of objects, without dropping or altering any object, name, or ACE, so policy findings are unchanged.
Policies read a descriptor via input.descriptors[obj.descriptor]. See the windows-*-strong-acls policies in the compliance-manifests repository.
type Report ¶
type Report struct {
Tool Tool `json:"tool"`
Objects []Object `json:"objects"`
Raw string `json:"raw"`
// contains filtered or unexported fields
}
Report is the structured projection of an AccessChk run.
Raw holds the full original text for inputs below RawRetentionLimit and is empty otherwise; descriptorMarker records whether an SDDL/descriptor marker was seen during parsing so LooksLikeAccessChk stays reliable even when Raw is omitted for oversized inputs. rawOmitted records whether the verbatim fallback fields were dropped because the input exceeded RawRetentionLimit, so callers can warn without knowing the input size upfront (see RawOmitted).
func Parse ¶
Parse converts AccessChk text output read from r into a Report. It streams r and never buffers the whole input, so it can parse a file handle directly without an intermediate full-file copy. It only returns an error when the input is not valid UTF-8 text or r fails; well-formed text always parses, with any unrecognized content preserved in the per-object RawLines and the top-level Raw field for inputs below RawRetentionLimit (see the package doc).
func (*Report) LooksLikeAccessChk ¶
LooksLikeAccessChk reports whether the parsed report resembles genuine AccessChk output. It is deliberately lenient: a recognizable banner, at least one parsed access entry, or an SDDL/descriptor marker is enough.
func (*Report) Project ¶ added in v1.106.2
func (r *Report) Project() (*Projection, error)
Project converts a parsed Report into its de-duplicated Projection. Two objects share a descriptor entry only when their descriptor fields are byte-for-byte identical, so no information is lost: every object keeps its own name and its exact descriptor, and the mapping is fully reconstructable.
func (*Report) RawOmitted ¶ added in v1.106.0
RawOmitted reports whether the verbatim fallback fields (Raw and the per-object RawLines) were dropped because the input exceeded RawRetentionLimit. It lets a streaming caller warn about the omission without measuring the input itself.
Source Files