3.3 kacs.audit.handle.used

4 min read

Event type: kacs.audit.handle.used
Defined in: kacs.evman
Tier: essential
Gating: the operation's required access overlaps the alarm mask cached on the handle
Cardinality: once per operation on the handle

The record of what was done with a handle after it was opened. Where kacs.audit.access.checked records the decision to open something, this records each subsequent use of it.

The mask is configured by SYSTEM_ALARM* ACEs at the access check that opened the handle, and the record is produced afterwards by whatever enforcement point handles the operation. FACS, for file handles, is the only such point today.

The subject is re-read on every operation. A handle outlives the token that opened it, so a process that starts or stops impersonating keeps its handles and every later operation is recorded under the token current at that moment. An investigation assuming the open-time identity will attribute later operations to the wrong principal.

Three masks appear together and are easy to confuse. Read as a sentence: the operation needed access.requested, of which access.matched triggered the audit, against a handle opened with access.granted, and it succeeded or did not.

3.3.1 Fields #

Field	Type	Presence	Meaning
`subject.token.sid`	`bin.sid`	via `subject`	The user SID of the effective token the operation ran under.
`subject.token.groups`	`bin.sid[]`	via `subject`	The group SIDs carried by the effective token.
`subject.token.group-attributes`	`uint.flags[]`	via `subject`	Per-group attribute bitmasks, positionally parallel to `subject.token.groups`.
`subject.token.integrity`	`uint.integrity`	via `subject`	The integrity RID of the effective token.
`subject.token.id`	`uint.luid`	via `subject`	The token's own LUID, identifying this specific token rather than the logon session it belongs to.
`subject.token.auth-id`	`uint.luid`	via `subject`	The LUID of the logon session the effective token belongs to.
`subject.token.type`	`str.enum`	via `subject`	Whether the effective token is a primary token or an impersonation token.
`subject.token.impersonation`	`uint.enum`	via `subject`	The impersonation level of the effective token.
`subject.token.uid`	`uint`	via `subject`	The Linux UID this token projects onto, for correlating a Peios event with Linux-side audit data.
`emitter.process.pid`	`uint`	via `subject`	The process ID the record was written from.
`emitter.process.name`	`str`	via `subject`	The kernel's name for the emitting process, typically the executable's basename.
`emitter.process.executable`	`str.path`	via `subject`	The path the emitting process was executed from, resolved at exec with symbolic links already followed.
`subject.pip.type`	`uint.enum`	via `subject`	The Protected Isolated Process type in force for the access check.
`subject.pip.trust`	`uint`	via `subject`	The PIP trust level in force for the access check.
`object.kind`	`str.enum`	required	Always `file` today, because FACS is the only enforcement point.
`object.file.path`	`str.path`	required	The absolute path of the file the operation acted on, resolved at the enforcement point.
`operation.name`	`str.enum`	required	Which operation was attempted. Values here (open set): `file.access` · `file.mmap` · `file.mprotect` · `file.permission` · `file.write` · `file.ioctl` · `file.lock` · `file.fcntl` · `file.truncate` · `file.fallocate`.
`access.requested`	`uint.mask`	required	What this operation needs — a read needs `FILE_READ_DATA`, an `mmap` with `PROT_EXEC` needs `FILE_EXECUTE`.
`access.matched`	`uint.mask`	required	The subset of the requested access that overlapped an audit mask and therefore caused the record to exist.
`access.granted`	`uint.mask`	required	What the handle was opened with, not what this operation was granted. An operation can only succeed if `access.requested` is a subset of it.
`access.audit-mask`	`uint.mask`	required	The full continuous-audit mask cached on a handle, of which `access.matched` is the part this operation touched.
`outcome.success`	`bool`	required	Whether the operation itself was allowed.
`outcome.reason`	`str.enum`	when `outcome.success == false`	From `KACS_FSR_*`, excluding `DECISION` (which names the ordinary path rather than a reason) and `AUDIT_EMIT_FAIL` (which cannot appear, being the failure of this record's own emission). Values here (open set): `signed-exec` · `grant-deny` · `append-deny` · `unmanaged-sysfs`.

Every record also carries the header fields of the envelope, which no payload repeats.

Generated from kacs.evman by pkm/tools/gen-events-book.py. Edit the fragment, not this page.

Edit this page