Inspecting security state

Inspection answers a specific question about the running system: who a process acts as, which session it belongs to, how it is protected, or what policy covers an object. Start with the supported command or desktop view for that question, and keep any access refusal or incomplete-view notice with the result.

For a failed operation, start with Debugging a denial. It puts the caller, object and requested action together before interpreting security state. A token dump alone does not tell you whether access is allowed.

What you can inspect #

These are read-only ways to begin. Replace PID, TID and ID with targets you have identified, and the example paths with the actual objects.

For files, sd check can explain a simulated access check without performing the file operation. Read the rehearsal's limits before treating its result as an explanation of an application's failure.

Who can inspect what #

The tool does not add authority. The underlying surface determines which checks apply:

• Another process's token: PROCESS_QUERY_INFORMATION on the process, PIP dominance, and TOKEN_QUERY on the token's own descriptor. Administrator membership does not bypass PIP or a changed token descriptor.
• Another process's PSB: PROCESS_QUERY_LIMITED on the process descriptor; PIP dominance is not required for this view. Seeing its protection does not grant access to its token or memory.
• Another process's descriptor: READ_CONTROL plus PIP dominance for owner, group and DACL inspection. SACL inspection additionally needs ACCESS_SYSTEM_SECURITY. See Inspecting processes.
• The kernel's full session listing: Administrators or SYSTEM, through the descriptor on /sys/kernel/security/kacs/sessions. logonse reports a refusal and can fall back to the sessions of processes you may inspect. Even an administrator's process list can omit protected processes.

Self-access is surface-specific. The Kernel TRM documents a process opening its own /proc token paths without the cross-process or token-descriptor checks. Opening its own token through the API still checks the token descriptor; a changed descriptor can revoke that access. Do not turn the first rule into a promise that every self-query succeeds. See Token access rights.

A refused inspection is a result in its own right. Keep the target, operation and error; ask an authorised operator or the component owner for the missing evidence when needed. Do not change permissions, disable protection or adjust a token just to obtain a fuller report.

What you cannot inspect #

These views have boundaries even when they return successfully:

• No complete history. They report current state. A destroyed token cannot be recovered from a live query, and an earlier impersonation or privilege state may have changed. Use recorded evidence for historical questions.
• No atomic machine snapshot. Processes and threads start and exit during a listing. Separate token queries can observe adjustments between reads; keep the token ID and modification counter where available.
• No global inventory of every token. Process-based inspection cannot list tokens held only by file descriptors with no running process using them.
• No implied access verdict. A token, PSB or descriptor report supplies inputs, not the outcome of every possible operation.
• No inferred absence from a partial view. Hidden processes, unreadable descriptor components and missing audit records remain unknown. A source or syscall error is not a successful empty result.

For registry output, use the documented result distinctions: reg exit 2 means a key/value was not found, 3 is access denied, and 5 is another syscall or source error. An empty value or listing alone is not one of those diagnoses. See reg exit status.

Standard query patterns #

Follow a process to its session. Find the process in Task Manager, inspect its primary token, and use the reported logon-session ID with logonse show ID. token show labels this session_id; in the underlying statistics it is auth_id. It is distinct from interactivity_scope. A service's impersonated request may belong to a different session, so retain which token you inspected.

Explain why a protected process has limited details. Read its Protection field in Task Manager or its PSB with logonse psb --pid PID. A visible PSB and a refused token query can both be correct under the separate access rules.

Investigate a privilege-related refusal. Use token privs --pid PID for the primary token, or the documented thread selector when impersonation is involved. Separate present from enabled; neither proves the application supplied any required intent or that another policy allowed the operation. Continue with Debugging a denial.

Two ways to read a token #

For an operator, token opens and queries the token, then renders readable output. Inspecting tokens explains how to select the target and interpret the fields.

For a tool author, token file descriptors and KACS_IOC_QUERY expose structured state. /proc/<pid>/token selects the process's primary token; /proc/<pid>/task/<tid>/token selects the thread's effective token. These and /sys/kernel/security/kacs/self provide handles, not text to print with cat. The SDK token-opening and query references document the programming interface; the Kernel TRM ABI notes cover the raw query protocol.

Other pseudo-files have different formats: the documented session listing and /proc/<pid>/psb are text. The existence of one text surface does not make token handles text, or make every surface follow the same access rules.

Where to start #

• Inspecting tokens: choose a token and interpret its identity, groups, privileges and restrictions.
• logonse and the session-listing reference: use the command for session reports; consult the reference for the underlying format.
• Task Manager and the process-inspection reference: use Task Manager for process views; consult the reference for the lower-level surfaces.
• Debugging a denial: combine these observations with the failed action and object policy.
• The event stream: raw transport diagnosis when events are not reaching eventd. For ordinary recorded-event inspection, use Event Viewer or evctl instead.

Start with the operation that failed, then gather the evidence you are allowed to read. The aim is to explain the refusal and decide whether the caller or the policy needs review. A refusal can be the intended protection working.

Use the inspection commands below before changing permissions, privileges or labels. An empty registry result or a missing process detail is not, by itself, evidence that a particular access-check layer denied the original operation.

Record the failed operation #

Keep these together:

• What failed and when: the application's message, error or exit status, timestamp, and the action you asked it to perform.
• The caller: the application or service, its PID, and the failing thread's TID if the application's diagnostics identify it. A service acting for a client may be using an impersonation token rather than its primary token.
• The object: the exact file path, registry key, process or other resource. For a file, establish whether the operation targeted a symbolic link or its target. For a registry operation, keep the key and value name separate.
• The access requested: read, write, execute, change permissions, or another specific operation. Keep the requested access mask when the diagnostic or audit record supplies it; an application may ask for more than its visible action suggests.
• The point of failure: opening an object, using an already-open handle, or a service's own authorisation check. These are different questions.

Access is normally decided when a handle is opened. Later operations use the rights stored on that handle; inspecting today's descriptor does not reconstruct what an older handle received. See The decision is made at open.

Find the thread and its tokens #

Use Task Manager to find the process by name, PID, person or service. Check its command, owner, service or job, and signed-in session where visible. Read any notice about hidden details or protection before interpreting the view.

In a terminal, use the read-only subcommands of token. Replace PID and TID with the identified process and thread:

token show --pid PID --all
token privs --pid PID
token show --pid PID --tid TID --all

--pid selects the process's primary token. The command's --tid selector is for a thread's impersonation token and is used with --pid; use it when investigating impersonation. The identity that matters is the one the failing thread used: its impersonation token while impersonating, otherwise its primary token. If that identity is no longer available, record the gap rather than substituting the inspection tool's own token. Running token show --all without a target shows the tool's own token, not another application's.

The /proc/<pid>/token, /proc/<pid>/task/<tid>/token and /sys/kernel/security/kacs/self surfaces provide token handles, not text to read with cat. The process path identifies the primary token; the thread path identifies the effective token. The command does the querying and decoding. Inspecting tokens documents those interfaces for tool authors.

Record the user SID, group attributes, token type and impersonation level, integrity and mandatory policy, present and enabled privileges, restricted SIDs, and confinement identity and capabilities where available. Keep token and session IDs with the time of inspection: the thread can revert impersonation, and token adjustments can change the state after the failure.

For process protection and session context, use logonse:

logonse psb --pid PID
logonse list
logonse show ID

Here ID is the logon-session ID you have identified. token show calls it session_id; it is separate from interactivity_scope. A PSB report shows protection, mitigations and the process GUID; it is not the process's security descriptor.

Inspection has its own access checks. Reading another process's token needs PROCESS_QUERY_INFORMATION, PIP dominance, and TOKEN_QUERY on the token. Reading its PSB needs PROCESS_QUERY_LIMITED and does not require PIP dominance. The full kernel session list is restricted to Administrators and SYSTEM; logonse can show a partial process-based view instead. A refused query or an absent process in that view is a limit on your evidence, not a reason to remove protection. See Who can inspect what.

Find the object and its SD #

For a file, sd show queries owner, group, DACL and the integrity-label subset:

sd show ./report.txt --all

Replace the example path with the object you identified. sd follows a named symbolic link by default; its documented --no-follow-symlinks option selects the link itself. Inspect the same object the failed operation meant to reach. --all changes formatting, not selection: this view does not include audit ACEs or the rest of the SACL, and its summaries omit some ACE payload details. Do not infer that undisplayed policy is absent.

For a registry key, reg sd prints owner, group and DACL by default:

reg sd Machine/App

Only when you already have the authority to read the SACL, request it explicitly:

reg sd Machine/App --sacl

The full SACL needs ACCESS_SYSTEM_SECURITY; the default registry owner/group/DACL view does not establish which SACL labels or policies exist. Similarly, a refused sd show is a failed inspection, not a decoded explanation of the original operation. Keep the returned error and the scope of any descriptor you obtained. For a process's descriptor, use the separate process-SD inspection reference with an authorised diagnostic tool; the PSB and a token report do not replace it.

In the parts you can read, look for:

• Owner and DACL: the owner SID, ordered allow/deny ACEs, inheritance flags, and the SIDs and rights each ACE names. INHERIT_ONLY (IO) rules apply to descendants rather than this object. A non-inherit-only access-control ACE naming OWNER RIGHTS suppresses the owner's implicit READ_CONTROL | WRITE_DAC grant.
• Mandatory label: the first applicable SYSTEM_MANDATORY_LABEL_ACE in the SACL and its policy bits.
• Process-trust label: an applicable SYSTEM_PROCESS_TRUST_LABEL_ACE and the rights its mask allows a non-dominant caller.
• Other policy inputs: scoped central-policy references (SYSTEM_SCOPED_POLICY_ID_ACE), resource attributes (SYSTEM_RESOURCE_ATTRIBUTE_ACE) and conditional ACEs.

A component omitted from your permitted view is unknown, not empty. Reading an owner or finding one allow ACE is not enough to establish effective access.

Rehearse a file check, within its limits #

For a file, sd check explains a check without performing the requested file operation:

sd check ./report.txt read --pid PID --explain

Choose the documented permission name or mask that matches the failed request. Without --pid, the check uses your own token. Save the explanation and any error, not just the exit status: a non-zero status can also mean the path was unreachable or the tool could not complete the check.

Treat this as evidence about the inputs tested. The command documents a process token selector, not a thread selector or switches for every optional access-check input. It does not establish that it reproduced a service's impersonated caller, local claims, backup/restore intent or process-trust context. It also does not test rights on an existing handle. An allowed rehearsal is not a guarantee that the application's full operation will succeed. If the result differs, compare the caller, target, requested rights and timing before changing policy.

Check audit evidence #

Check the recorded attempt alongside the live state, rather than treating logs as a last resort. In Event Viewer, select the relevant time range and filter Type to kacs.audit.access.checked. Select a record to inspect its fields. The terminal route is Using evctl.

Correlate the timestamp, emitting process, subject token/session and object information actually present in the record. The subject is the caller; an object.process.* or object.token.* field identifies the target. Some checks cannot supply a path or a complete object identity, so do not infer one.

For a matching access-check record:

• Compare access.requested and access.granted. The requested mask is already generic-mapped to the object's rights.
• access.denied-integrity and access.denied-trust, when present, identify bits withheld by the mandatory-integrity or process-trust checks.
• trigger.ace identifies the audit ACE that caused a SACL-driven record; it is not a trace naming the DACL ACE that denied access.
• fields.attestation.userspace marks an advisory syscall check whose descriptor and supplied context came from userspace. It is not proof that the real operation used those same inputs.

For a kacs.audit.privilege.used record with operation.name equal to access-check, a false outcome.success means a privilege contributed rights that did not survive. It does not mean the privilege was absent, and it does not identify one narrowing layer on its own.

No record is not proof of no attempt. Access auditing depends on matching SACL rules or token policy, and syscall SACL records additionally require the calling process's enabled SeAuditPrivilege. Reader permissions, query scope, retention and transport loss also limit what you can see. One check can produce several records; MAXIMUM_ALLOWED success is not evidence that a particular right was granted, and it produces no access-check privilege-use record. See Find missing records.

Use the raw event stream only to diagnose the transport itself. It requires SeSecurityPrivilege, can lose events, and is not a replacement for recorded history.

The six places a denial can come from #

For a completed access check, these are the common policy questions. They are not a classification of every application error or failed inspection:

1. Could the impersonation token be used for access at all?
2. Did mandatory integrity control (MIC) withhold the requested rights?
3. Did process integrity protection (PIP) withhold them?
4. Did the DACL grant them for this caller?
5. Did a restricted-token pass, confinement or central policy narrow the grant?
6. Did an operation that legitimately needs a privilege have it present, enabled and, where required, accompanied by the caller's intent?

Review the relevant policy #

Use the evidence above to choose the relevant review below. The access-decision overview explains the complete ordering; a visible allow rule or a hand-worked DACL alone is not a full verdict.

Impersonation level #

An impersonation-type token at Identification level cannot be used for an access check. Confirm the type as well as the level. Ask the application's owner to review what the client requested and whether the two-gate model downgraded it. Identification may have been deliberate; do not assume the client intended to delegate more authority.

MIC #

Compare the caller's integrity and mandatory policy with the object's applicable mandatory label and the requested rights. NO_READ_UP, NO_WRITE_UP and NO_EXECUTE_UP affect the corresponding mapped categories. An object without an applicable label defaults to Medium with no-write-up; an unreadable SACL does not establish that this default applies.

Review whether the workload was launched at its intended integrity and whether the object's label matches its purpose. Do not lower a label or elevate the caller merely to make the test pass. MIC does not revoke rights already granted by backup/restore privileges, so an integrity mismatch alone is not the full answer. See Mandatory integrity control.

PIP #

PIP compares process trust, not the user's identity or token integrity. Both caller trust axes must dominate the object's applicable trust label; otherwise the label's mask limits the allowed rights and can revoke privilege grants. Use the permitted PSB view and any recorded access.denied-trust evidence.

For a protected service, review whether the client is using its supported interface and intended binary. Administrator membership or another privilege does not bypass this boundary. Review unexpected protection or signing state with the component owner. See Process integrity protection.

Privileges #

First establish that this operation is intended to use a privilege. Then separate three findings:

• Absent: review the principal's privilege assignment with its policy owner.
• Present but disabled: review the application's use of that privilege.
• Enabled but intent missing: backup/restore intent belongs to the caller's operation, and cannot be inferred from the token dump.

A privilege's presence is not a general access grant. Enabling privileges or adding backup/restore intent is not a routine repair for an ordinary read or write. PIP, confinement and central policy can still constrain privilege-granted rights. See Privileges in the pipeline and Intent-gated privileges.

The DACL walk #

Compare the requested rights with the ordered ACEs and the caller's actual SID set. Enabled groups participate in allows; deny-only groups participate in denies. Check INHERIT_ONLY, owner-rights suppression and inherited rules before concluding that a rule applies. For conditional ACEs, missing claims or resource attributes can produce UNKNOWN, which does not grant access through an allow ACE.

ACE order matters: the walk is first-writer-wins for each undecided right, not a search for any matching allow. Use DACL evaluation and Ownership for the exact matching rules, including OWNER RIGHTS and PRINCIPAL_SELF.

If the evidence points to the DACL, ask the resource's policy owner to compare its intended audience and rights with the current rules and inheritance. Avoid broad grants, ownership changes or inheritance resets as diagnostic shortcuts.

Narrowing layers #

A DACL grant may still be narrowed:

• Restricted token: compare the restricting SIDs with the object's rules. The write-restricted variant narrows only write-category rights. Privilege grants can survive this pass; review the application's token construction.
• Confinement: compare the confinement SID and declared capabilities with the resource policy. Privileges do not bypass confinement. Review the workload's intended capabilities with its deployment or policy owner.
• Central access policy (CAAP): check referenced effective policies, their applicability and resource attributes with the directory/policy owner. A missing policy uses the documented recovery policy. A staged-policy mismatch is a rollout signal, not a statement that the staged policy caused the denial.

Do not remove restrictions, confinement or central-policy references to test a hypothesis. See Narrowing layers for the separate mechanisms and their policy-specific references.

A compact checklist #

1. Keep the failing action, time, caller, object, requested rights and exact error together.
2. Identify the process in Task Manager; inspect the relevant token and PSB using the documented commands and your existing authority.
3. Read the descriptor components you are allowed to see. Mark inaccessible components as unknown.
4. For a file, use sd check --explain with the identified target and rights; record which inputs the rehearsal does and does not reproduce.
5. Correlate available audit evidence. Account for missing records and changes since the failure.
6. Take the finding to the appropriate application or policy owner. After an approved correction, verify the original operation in its intended context; a changed descriptor or an allowed rehearsal alone is not completion.

When the evidence is incomplete #

Hand the investigation to the application or resource-manager developer when the failure depends on a transient impersonation token, caller-supplied claims, intent flags, object-type mapping or other inputs the operator tools cannot reproduce. Include the evidence collected, its timestamps and scope, and each inspection that was refused. Do not fill missing inputs with guesses.

The existing SDK checking-access guide covers programmatic evaluation. Its request reference defines the token, descriptor, desired mask, generic mapping, privilege intent, self SID, local claims, object tree, PIP context and audit context. The check and audit outputs references describe the granted mask, continuous-audit mask and staging-mismatch flag. The Kernel TRM KACS ABI preserves the raw syscall structures.

These checks are advisory. A developer must match the original inputs and understand the syscall's audit limits before treating a reproduction as an explanation. Calling or decoding a syscall is not a required operator step, and its answer does not perform or authorise the original operation.

Where to go next #

• Task Manager and token for identifying the caller.
• sd and registry access control for the object's policy and the supported inspection commands.
• Event Viewer and Find missing records for recorded evidence and the limits of a search.
• Inspecting security state for the underlying interfaces and access requirements.

Use the read-only forms of token to learn who a process acts as and what identity, privileges and restrictions its token carries. Choose the target first: the inspection tool's token, a process's primary token and a thread's impersonation token can describe different callers.

A report is current state, not a record of an earlier failure and not a list of everything that caller may access. For a denial, keep the object and requested operation alongside it; follow Debugging a denial.

Reading from the shell #

Start with a summary, then request only the detail needed:

token
token show --all
token show --pid PID --all
token groups --pid PID
token privs --pid PID
token stats --pid PID

The first two inspect the token running the command. --pid PID selects the identified process's primary token. Use Task Manager to find and check the process rather than guessing its PID.

For impersonation, the command documents --tid TID together with --pid PID:

token show --pid PID --tid TID --all

The failing thread's effective token is its impersonation token while impersonating, otherwise the primary token. A primary-token report cannot stand in for an impersonated client's identity. If the thread has exited or reverted, keep that limitation with the result. Do not assume a query made later reconstructs the token used earlier.

The other documented selectors are --self (the default), --real (your primary token specifically), and --peer SOCK_FD (a connected socket's captured peer identity). A peer token is the identity conveyed on that connection, not a general lookup of another process. See Choosing which token.

--raw prints raw SIDs, --label uses labels where known, and --json requests structured output. Preserve the selector, timestamp and any error with a saved report. The command also has mutating subcommands; adjusting, duplicating, restricting or impersonating a token is not part of read-only inspection.

Read the fields as evidence #

Apply the same target selector to these field commands; without it they inspect your own token. token query CLASS is the documented raw named-class JSON form for tooling. The complete class numbers and payloads are maintained in the Kernel ABI and token query payload reference, rather than duplicated here.

show --all means every supported query class, not every internal token field. The ABI notes explicitly list fields with no query class, including audit_policy, write_restricted and confinement_exempt. Do not infer these from their absence in a report.

Patterns by use case #

Who was this thread acting as? Use the process and thread identity supplied by the failure report, inspect the relevant token, and distinguish its type from its impersonation level. A primary token also carries an impersonation ceiling; the level alone does not tell you that the thread is impersonating. For earlier state, correlate the available audit record instead.

Which session is this? token show displays the LogonSession LUID as session_id; the underlying statistics field is auth_id. interactivity_scope is a separate interactive-environment scope. Use the logon session ID with logonse show ID, subject to the session view's access limits.

Is this the elevated half of a token pair? The elevation type can be Full, Limited or Default. Full and Limited describe the two sides of a linked pair; Default means the token is not part of one. This is evidence about the token, not a recommendation to elevate it. The separate token linked command reports a linked counterpart where accessible.

Did the token change? Token statistics include its ID and modified_id, which changes on adjustment. Keep both when comparing observations. Several queries are not an atomic snapshot, and replacing a thread's token is not the same as adjusting the one you previously inspected.

Would this token be allowed to access an object? The token is only one input. For a file, use the documented sd check rehearsal and its limits. For other objects or caller-specific inputs, use their supported diagnostic path or ask the component owner to investigate.

Limits and refused queries #

• Reading another process's token needs PROCESS_QUERY_INFORMATION, PIP dominance and the token's own TOKEN_QUERY grant. A refusal does not tell you which of those checks failed. Protected processes can remain closed to an administrator.
• Self-access depends on the surface. The documented own-process /proc token path is query-only without those checks; a direct self-open API checks the token's descriptor and can be denied after that descriptor changes.
• A missing or exited target, a denied query and an invalid request are different results. Keep the tool's message; a failed query is not an empty token.
• Process-based inspection cannot enumerate tokens held only by descriptors. Current queries cannot recover a destroyed token or historical fields.
• Queries do not grant adjustment, installation, duplication or impersonation rights. The used privilege state is not a timestamped history of each use; use audit evidence for that question.

See Token access rights for the per-surface checks and Inspecting security state for related views.

Obtaining a token fd #

This is the tool-author boundary. Token pseudo-files are handles, not human-readable text: cat /proc/<pid>/token is not an inspection command. The process path selects the primary token and /proc/<pid>/task/<tid>/token selects the thread's effective token; the /sys/kernel/security/kacs/self surface also provides a token handle.

The SDK opening reference covers self, process, thread and socket-peer token acquisition and error results. The Kernel TRM access-rights chapter documents the query-only /proc handles, fixed peer-token rights, descriptor checks and cached handle rights. A handle with only TOKEN_QUERY cannot perform operations requiring other token rights.

KACS_IOC_QUERY #

Operators use token to perform and decode queries. Tool authors should start with the SDK query reference and two-call buffer protocol. The SDK provides typed readers for common fields and the generic class reader for the rest.

For a raw-ABI consumer, the preserved querying-a-token-handle explanation covers KACS_IOC_QUERY, size probes, short buffers and the two-call sequence. The generated KACS ABI holds the exact ioctl number, argument layout and class constants; its ABI notes define the returned bytes. There is no need to decode those bytes by hand to follow this operator workflow.

See also #

• token: the complete command interface.
• Debugging a denial: caller, object, requested action and audit evidence together.
• Tokens: the identity model behind the fields.
• Working with tokens: developer tasks using the SDK.