# 3.11 kacs.impersonation.started

_Peios / Using Peios / Events / Access and Identity Events_

> The record that a thread took on, or tried to take on, a client's identity by impersonating its token.

- **Event type:** `kacs.impersonation.started`
- **Defined in:** `kacs.evman`
- **Tier:** standard
- **Gating:** none — every impersonation attempt that names a client token is recorded
- **Cardinality:** once per attempt

The record that a thread took on, or tried to take on, a client's identity
by impersonating its token. The subject is the server — the token that
acted, as it stood before the switch — and the object is the client token.
Successes and refusals are both recorded.

Impersonation is per thread, so `emitter.thread.tid` names the thread that
changed identity, not `emitter.process.pid`. Records the thread writes
afterwards carry the client's token in their header, until a
`kacs.impersonation.reverted` record ends it.

**The level can be lowered without the attempt failing.**
`object.token.impersonation` is the level the client token offered, and
`object.token.impersonation-permitted` the level KACS let the server have.
Where the second is lower — the server lacked SeImpersonatePrivilege for a
different user, or the client's integrity was above the server's — the
impersonation succeeded at Identification, which can query the client's
identity but not act as it.

**The GUID is the installed token's.** A lowered level installs a new token,
so `object.token.guid` and `object.token.id` on a success are that token's,
and they match the `emitter.token.guid` of the thread's later records.
Exactly when the level was lowered they differ from the GUID of the token
the client handed over.

## 3.11.1 Fields

| Field | Type | Presence | Meaning |
|---|---|---|---|
| [`subject.token.sid`](/peios/using-peios/events/field-index/fields-subject.md#subject.token.sid) | `bin.sid` | via [`subject`](/peios/using-peios/events/groups/group-subject.md) | The user SID of the effective token the operation ran under. |
| [`subject.token.groups`](/peios/using-peios/events/field-index/fields-subject.md#subject.token.groups) | `bin.sid[]` | via [`subject`](/peios/using-peios/events/groups/group-subject.md) | The group SIDs carried by the effective token. |
| [`subject.token.group-attributes`](/peios/using-peios/events/field-index/fields-subject.md#subject.token.group-attributes) | `uint.flags[]` | via [`subject`](/peios/using-peios/events/groups/group-subject.md) | Per-group attribute bitmasks, positionally parallel to `subject.token.groups`. |
| [`subject.token.integrity`](/peios/using-peios/events/field-index/fields-subject.md#subject.token.integrity) | `uint.integrity` | via [`subject`](/peios/using-peios/events/groups/group-subject.md) | The integrity RID of the effective token. |
| [`subject.token.id`](/peios/using-peios/events/field-index/fields-subject.md#subject.token.id) | `uint.luid` | via [`subject`](/peios/using-peios/events/groups/group-subject.md) | The token's own LUID, identifying this specific token rather than the logon session it belongs to. |
| [`subject.token.auth-id`](/peios/using-peios/events/field-index/fields-subject.md#subject.token.auth-id) | `uint.luid` | via [`subject`](/peios/using-peios/events/groups/group-subject.md) | The LUID of the logon session the effective token belongs to. |
| [`subject.token.type`](/peios/using-peios/events/field-index/fields-subject.md#subject.token.type) | `str.enum` | via [`subject`](/peios/using-peios/events/groups/group-subject.md) | Whether the effective token is a primary token or an impersonation token. |
| [`subject.token.impersonation`](/peios/using-peios/events/field-index/fields-subject.md#subject.token.impersonation) | `uint.enum` | via [`subject`](/peios/using-peios/events/groups/group-subject.md) | The impersonation level of the effective token. |
| [`subject.token.uid`](/peios/using-peios/events/field-index/fields-subject.md#subject.token.uid) | `uint` | via [`subject`](/peios/using-peios/events/groups/group-subject.md) | The Linux UID this token projects onto, for correlating a Peios event with Linux-side audit data. |
| [`emitter.process.pid`](/peios/using-peios/events/field-index/fields-emitter.md#emitter.process.pid) | `uint` | via [`subject`](/peios/using-peios/events/groups/group-subject.md) | The process ID the record was written from. |
| [`emitter.process.name`](/peios/using-peios/events/field-index/fields-emitter.md#emitter.process.name) | `str` | via [`subject`](/peios/using-peios/events/groups/group-subject.md) | The kernel's name for the emitting process, typically the executable's basename. |
| [`emitter.process.executable`](/peios/using-peios/events/field-index/fields-emitter.md#emitter.process.executable) | `str.path` | via [`subject`](/peios/using-peios/events/groups/group-subject.md) | The path the emitting process was executed from, resolved at exec with symbolic links already followed. |
| [`subject.pip.type`](/peios/using-peios/events/field-index/fields-subject.md#subject.pip.type) | `uint.enum` | via [`subject`](/peios/using-peios/events/groups/group-subject.md) | The Protected Isolated Process type in force for the access check. |
| [`subject.pip.trust`](/peios/using-peios/events/field-index/fields-subject.md#subject.pip.trust) | `uint` | via [`subject`](/peios/using-peios/events/groups/group-subject.md) | The PIP trust level in force for the access check. |
| [`emitter.thread.tid`](/peios/using-peios/events/field-index/fields-emitter.md#emitter.thread.tid) | `uint` | required | The thread that wrote the record, where the operation is scoped to a thread rather than to its process. |
| [`object.kind`](/peios/using-peios/events/field-index/fields-object.md#object.kind) | `str.enum` | required | Always `token`. |
| [`object.token.guid`](/peios/using-peios/events/field-index/fields-object.md#object.token.guid) | `bin.guid` | required | The durable GUID of the token the operation acted on. |
| [`object.token.id`](/peios/using-peios/events/field-index/fields-object.md#object.token.id) | `uint.luid` | required | The LUID of the token the operation acted on, for token-open and token-adjust checks. |
| [`object.token.sid`](/peios/using-peios/events/field-index/fields-object.md#object.token.sid) | `bin.sid` | required | The client: whose identity the server took on or asked for. |
| [`object.token.type`](/peios/using-peios/events/field-index/fields-object.md#object.token.type) | `str.enum` | required | `primary` only on a refusal: a primary token cannot be impersonated. |
| [`object.token.integrity`](/peios/using-peios/events/field-index/fields-object.md#object.token.integrity) | `uint.integrity` | required | The integrity level of the token the operation acted on, as an integrity RID. |
| [`object.token.auth-id`](/peios/using-peios/events/field-index/fields-object.md#object.token.auth-id) | `uint.luid` | optional | Absent only for a token with no logon session. |
| [`object.token.restricted`](/peios/using-peios/events/field-index/fields-object.md#object.token.restricted) | `bool` | required | Whether the token is restricted: whether it carries restricting SIDs that every access check must also satisfy. |
| [`object.token.impersonation`](/peios/using-peios/events/field-index/fields-object.md#object.token.impersonation) | `uint.enum` | required | The level the client token offered: the level asked for. |
| [`object.token.impersonation-permitted`](/peios/using-peios/events/field-index/fields-object.md#object.token.impersonation-permitted) | `uint.enum` | optional | The level the gate allowed. Absent when the attempt was refused before the gate answered. |
| [`privilege.name`](/peios/using-peios/events/field-index/fields-privilege.md#privilege.name) | `str.enum` | optional | `SeImpersonatePrivilege`, present when the server impersonated a different user, or across a restriction difference, and needed the privilege to do it at the level asked. The privilege is then marked used. |
| [`privilege.held`](/peios/using-peios/events/field-index/fields-privilege.md#privilege.held) | `bool` | when `privilege.name == SeImpersonatePrivilege` | Always true where present: a server without the privilege is not refused but lowered to Identification, which `impersonation-permitted` shows. |
| [`outcome.success`](/peios/using-peios/events/field-index/fields-outcome.md#outcome.success) | `bool` | required | Whether the operation succeeded. |
| [`outcome.errno`](/peios/using-peios/events/field-index/fields-outcome.md#outcome.errno) | `int.errno` | when `outcome.success == false` | The error the operation failed with, as a negative errno. |
| [`outcome.reason`](/peios/using-peios/events/field-index/fields-outcome.md#outcome.reason) | `str.enum` | optional | On a refusal, where KACS knows why: the token handed over was a primary token (`EINVAL`); a restricted server tried to impersonate an unrestricted token of its own user, which would escape its restriction (`EPERM`); the token handle lacked `TOKEN_IMPERSONATE` (`EACCES`); or the identity could not be projected onto the thread's Linux credentials. Absent on a refusal for want of memory.<br><br>Values here (open set): `primary-token` · `restriction-escape` · `no-impersonate-access` · `projection-failed`. |

Every record also carries the header fields of [the envelope](/peios/using-peios/events/introduction/the-envelope.md), which no payload repeats.

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