Skip to content

Resolved #307 Resolved #308 - Updated documentation based on implementation docs and clarified when an item should be created #310

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
vanderpol wants to merge 1 commit into
base: 5.12.3_develop
Choose a base branch
from
+31 −2
Open

Resolved #307 Resolved #308 - Updated documentation based on implementation docs and clarified when an item should be created #310

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 8 additions & 1 deletion oval-schemas/windows-definitions-schema.xsd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3931,6 +3931,8 @@
<xsd:documentation>The ntuser test is used to check metadata associated with Windows ntuser.dat files. It extends the standard TestType as defined in the oval-definitions-schema and
one should refer to the TestType description for more information. The required object element references a ntuser_object and the optional state element specifies the ntuser
data to check.</xsd:documentation>

<xsd:documentation>To ensure consistent results across OVAL interpreters, application developers should refer to documentation in the ntuser_item when implenting this test.</xsd:documentation>
<xsd:appinfo>
<oval:element_mapping>
<oval:test>ntuser_test</oval:test>
Expand Down Expand Up @@ -4035,11 +4037,13 @@
<xsd:element name="key" type="oval-def:EntityStateStringType" minOccurs="0">
<xsd:annotation>
<xsd:documentation>This element describes a registry key normally found in the HKCU hive to be tested.</xsd:documentation>
<xsd:documentation>Note: The key not existing on the target does not impact the overall existence of the ntuser_item.</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="name" type="oval-def:EntityStateStringType" minOccurs="0">
<xsd:annotation>
<xsd:documentation>This element describes the name of a value of a registry key.</xsd:documentation>
<xsd:documentation>Note: The name not existing on the target does not impact the overall existence of the ntuser_item.</xsd:documentation>
Copy link
Copy Markdown

@solind solind May 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If there is an item with a corresponding name, the object will be said to exist.

Anyway, this is documentation for the state entity. If the state specifies a name that doesn't match any item, then no items will match that state. The effect on existence comes into play only if the state is used to filter an object or set.

</xsd:annotation>
</xsd:element>
<xsd:element name="sid" type="oval-def:EntityStateStringType" minOccurs="0">
Expand All @@ -4062,16 +4066,18 @@
<xsd:element name="logged_on" type="oval-def:EntityStateBoolType" minOccurs="0">
<xsd:annotation>
<xsd:documentation>The logged_on element describes if the user account is currently logged on to the computer.</xsd:documentation>
<xsd:documentation>This can be determined by comparing the SID’s against those populated in HKEY_USERS</xsd:documentation>
Copy link
Copy Markdown

@solind solind May 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The active user logon sessions can also be determined using the WMI classes Win32_LoggedOnUser and Win32_LogonSession. I'm not sure whether the presence of a hive under HKEY_USERS is completely reliable for the purpose of whether the user should actually be considered "logged on".

I recall we considered interactive and remote interactive session types to be logged on.

</xsd:annotation>
</xsd:element>
<xsd:element name="days_since_last_logon" type="oval-def:EntityStateIntType" minOccurs="0" maxOccurs="1">
<xsd:annotation>
<xsd:documentation>The last_logon data, converted to days and then rounded down to the nearest integer (floor function). If the account is determined to be currently logged in, this date should be reported as 0.</xsd:documentation>
<xsd:documentation>The last_logon data which can be obtained from the LocalProfileLoadTimeHigh and LocalProfileLoadTimeLow values, converted to days and then rounded down to the nearest integer (floor function). If the account is determined to be currently logged in, this date should be reported as 0.</xsd:documentation>
Copy link
Copy Markdown

@solind solind May 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Where are these obtained from? Registry values somewhere under HKLM?

Data can also be obtained from the WMI table Win32_NetworkLoginProfile.

</xsd:annotation>
</xsd:element>
<xsd:element name="enabled" type="oval-def:EntityStateBoolType" minOccurs="0">
<xsd:annotation>
<xsd:documentation>The enabled element describes if the user account is enabled or disabled.</xsd:documentation>
<xsd:documentation>Note: For domain users, if a domain controller is not available, this will not return data. If using this data for a filter to include enabled accounts, it’s recommended to exclude accounts that are have been determined to be disabled, vs including ones that are enabled, as the later may filter out accounts for which the domain controller could not return data.</xsd:documentation>
Copy link
Copy Markdown

@solind solind May 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we'd have to say that the element would be status="not_collected" (IIRC) if the domain server is unavailable, which (for good or ill) has documented evaluation effects. Or, it could have an error status.

</xsd:annotation>
</xsd:element>
<xsd:element name="date_modified" type="oval-def:EntityStateIntType" minOccurs="0">
Expand All @@ -4088,6 +4094,7 @@
<xsd:element name="filepath" type="oval-def:EntityStateStringType" minOccurs="0">
<xsd:annotation>
<xsd:documentation>This element describes the filepath of the ntuser.dat file.</xsd:documentation>
<xsd:documentation>The existance of each ntuser.dat file determines the overall ntuser_item existence.</xsd:documentation>
Copy link
Copy Markdown

@solind solind May 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I hate to get into semantics, but I think you mean to be talking about the existence of the object, not the item. The object exists if all its criteria are satisfied by one or more items discovered on the target machine.

</xsd:annotation>
</xsd:element>
<xsd:element name="last_write_time" type="oval-def:EntityStateIntType" minOccurs="0">
Expand Down
24 changes: 23 additions & 1 deletion oval-schemas/windows-system-characteristics-schema.xsd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1629,6 +1629,22 @@
<xsd:element name="ntuser_item" substitutionGroup="oval-sc:item">
<xsd:annotation>
<xsd:documentation>The windows ntuser_item specifies information that can be collected from a particular ntuser.dat file.</xsd:documentation>
<xsd:documentation>To ensure consistent results across OVAL interpreters, the following implementation methods are recommended. Note that there may be other technical ways to obtain the data, which vendors may choose to implement.</xsd:documentation>
<xsd:documentation>1. Finding Human User Profiles </xsd:documentation>
<xsd:documentation> a. Obtain a list of User Profiles from the following registry key, where each subkey is a profile that may be included in scope for this test</xsd:documentation>
<xsd:documentation> i. HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\WindowsNT\CurrentVersion\ProfileList</xsd:documentation>
<xsd:documentation> b. Determine which user profiles are from ‘human’ users</xsd:documentation>
<xsd:documentation> i. Exclude profiles for LocalService, Network service etc.. by excluding subkeys in the format of S-1-5-&lt;number*gt;</xsd:documentation>
<xsd:documentation> ii. Exclude profiles for Per-Service SIDs by excluding subkeys in the format of S-1-5-80-&lt;number*gt;-&lt;number*gt;-&lt;number*gt;-&lt;number*gt;-&lt;number*gt;</xsd:documentation>
<xsd:documentation> iii. Include Local and Domain User SIDs by including subkeys match the format of S-1-5-21-&lt;number*gt;-&lt;number*gt;-&lt;number*gt;-&lt;number*gt;</xsd:documentation>
<xsd:documentation> c. Obtain ntuser filepath from the ProfileImagePath value of 'human' profiles</xsd:documentation>
<xsd:documentation>2. Creating ntuser items</xsd:documentation>
<xsd:documentation>If the filepath obtained from the ProfileImagePath exists on the target system, create a ntuser_item with a status of 'exists'</xsd:documentation>
Copy link
Copy Markdown

@solind solind May 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is basically saying that all NTUSER objects always exist, assuming there is at least one user profile on the target machine (there should always be at least one). I don't think that's right, but... it's been a long time.

<xsd:documentation>3. Gathering per user registry key data</xsd:documentation>
<xsd:documentation> a. If a user is logged in, their ntuser.dat file will be locked and the OVAL interpreter will not be able to read it, the OVAL interpreter will need to obtain that data from HKEY_USERS\&lt;sid_of_logged_in_user&gt;</xsd:documentation>
<xsd:documentation> b. If a user is not logged in, the OVAL interpreter will need to obtain the data directly from the users ntuser.dat file.</xsd:documentation>
<xsd:documentation> Note: There are many different methods depenending on programming language to parse ntuser.dat files, and each OVAL interpreter may choose their own methods.</xsd:documentation>
<xsd:documentation> If no other programming language native methods are available, it is advised not to load the ntuser.dat file directly from its original location, as it will lock the file and prevent that user from logging into Windows. The file will need to be copied/renamed to a temporary location and then loaded, used and unloaded and removed.</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:complexContent>
Expand All @@ -1637,13 +1653,15 @@
<xsd:element name="key" type="oval-sc:EntityItemStringType" minOccurs="0" maxOccurs="1">
<xsd:annotation>
<xsd:documentation>This element describes a registry key normally found in the HKCU hive to be tested.</xsd:documentation>
<xsd:documentation>Note: The key not existing does not impact the overall existence of the ntuser_item.</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="name" type="oval-sc:EntityItemStringType" minOccurs="0" maxOccurs="1" nillable="true">
<xsd:annotation>
<xsd:documentation>This element describes the name of a registry key. If the xsi:nil attribute is set to true, then the item being represented is the
higher level key. Using xsi:nil here will result in a status of 'does not exist' for the type, and value entities since these entities are not
associated with a key by itself.</xsd:documentation>
<xsd:documentation>Note: The name not existing does not impact the overall existence of the ntuser_item.</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="sid" type="oval-sc:EntityItemStringType" minOccurs="0" maxOccurs="1">
Expand All @@ -1656,6 +1674,7 @@
<xsd:documentation>The username entity holds a string that represents the name of a particular user. In Windows, user names are case-insensitive. As a
result, it is recommended that the case-insensitive operations are used for this entity. In a domain environment, users should be identified in
the form: "domain\user name". For local users use: "computer name\user name".</xsd:documentation>
<xsd:documentation>Note: When gathering the built-in Guest and build-in Administrator, they may not resolve and may need to have the ComputerName prepended to it.</xsd:documentation>
Copy link
Copy Markdown

@solind solind May 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The built-in guest and administrator accounts may actually be renamed. They are really only recognizable using their SIDs. I believe the username convention here should follow those used for other Windows user objects.

</xsd:annotation>
</xsd:element>
<xsd:element name="account_type" type="win-sc:EntityItemNTUserAccountTypeType" minOccurs="0" maxOccurs="1">
Expand All @@ -1666,16 +1685,18 @@
<xsd:element name="logged_on" type="oval-sc:EntityItemBoolType" minOccurs="0" maxOccurs="1">
<xsd:annotation>
<xsd:documentation>The logged_on element describes if the user account is currently logged on to the computer.</xsd:documentation>
<xsd:documentation>This can be determined by comparing the SIDs collected from the ProfileList against those populated in HKEY_USERS</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="days_since_last_logon" type="oval-sc:EntityItemIntType" minOccurs="0" maxOccurs="1">
<xsd:annotation>
<xsd:documentation>The last_logon data, converted to days and then rounded down to the nearest integer (floor function). If the account is determined to be currently logged in, this date should be reported as 0.</xsd:documentation>
<xsd:documentation>The last_logon data, which can be obtained from the LocalProfileLoadTimeHigh and LocalProfileLoadTimeLow values, converted to days and then rounded down to the nearest integer (floor function). If the account is determined to be currently logged in, this date should be reported as 0.</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="enabled" type="oval-sc:EntityItemBoolType" minOccurs="0" maxOccurs="1">
<xsd:annotation>
<xsd:documentation>The enabled element describes if the user account is enabled or disabled.</xsd:documentation>
<xsd:documentation>Note: For domain users, if a domain controller is not available, this will not return data. If using this data for a filter to include enabled accounts, it’s recommended to exclude accounts that are have been determined to be disabled, vs including ones that are enabled, as the later may filter out accounts for which the domain controller could not return data.</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="date_modified" type="oval-sc:EntityItemIntType" minOccurs="0" maxOccurs="1">
Expand All @@ -1692,6 +1713,7 @@
<xsd:element name="filepath" type="oval-sc:EntityItemStringType" minOccurs="0" maxOccurs="1">
<xsd:annotation>
<xsd:documentation>This element describes the filepath of the ntuser.dat file.</xsd:documentation>
<xsd:documentation>The existance of each ntuser.dat file determines the overall ntuser_item existence.</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="last_write_time" type="oval-sc:EntityItemIntType" minOccurs="0" maxOccurs="1">
Expand Down