security.windows

Windows security identifiers, access-control lists, and security descriptors.

Security descriptors, ACLs, and ACEs each have a declarative form accepted in place of a built value: SecDescSpec, AclSpec, and AceSpec. The lowercase sec_desc, acl, and ace functions build values from them, as do the update_sec_desc functions of other modules. The type constructors are strict and accept only built components.

let descriptor = sec_desc
  owner: :BUILTIN_ADMINISTRATORS:
  dacl_protected: true
  dacl:
    - allow: :LOCAL_SYSTEM:
      mask: :GENERIC_ALL:
    - allow: :BUILTIN_USERS:
      mask: :GENERIC_READ:
      flags: [:OBJECT_INHERIT:, :CONTAINER_INHERIT:]

Types

Type	Description
`AccessMask`	Generic Windows object access rights.
`Ace`	Immutable view of a native Windows access-control entry.
`AceFlags`	Flags stored in an ACE header.
`Acl`	Immutable view of a native Windows access-control list.
`SecDesc`	Windows security descriptor.
`SecDescControl`	Security descriptor control flags.
`SecInfo`	Security descriptor components loaded by a query.
`Sid`	Windows security identifier.
`SidName`	Resolved Windows account identity.
`TokenGroup`	A group in a Windows access token.
`TokenGroupAttributes`	Windows access-token group attributes.
`TokenInfo`	Windows access token information.
`AccessMaskSpec`	An access mask, built or given as right symbols or native bits. A subtype such as `winreg.AccessMask` is accepted too.
`AccessRight`	A symbol naming rights of an `AccessMask`.
`AceFlag`	A symbol naming a flag of an `AceFlags`.
`AceFlagsSpec`	ACE header flags, built or given as flag symbols or native bits.
`AceSpec`	An ACE, built or given as a dictionary.
`AceType`	A native ACE type, or `:UNKNOWN:` for an unrecognized type code.
`AclRevision`	A named ACL revision. A native revision number is accepted wherever one of these is.
`AclSpec`	An ACL, built or given as its entries in packet order.
`IdentifierAuthority`	The identifier authority of a SID.
`SecDescControlFlag`	A symbol naming a flag of a `SecDescControl`.
`SecDescSpec`	A security descriptor, built, given as a self-relative packet, or given as a dictionary of the component arguments of `sec_desc`.
`SecInfoComponent`	A symbol naming components of a `SecInfo`.
`SidNameUse`	How Windows classifies a resolved SID.
`SidSpec`	A SID, built or spelled as its canonical string, its native packet, or a well-known SID.
`TokenGroupAttribute`	A symbol naming an attribute of a `TokenGroupAttributes`.
`WellKnownSid`	A SID that is the same on every Windows installation, so naming one takes no lookup.

`AccessMaskSpec = (AccessMask | Int | AccessRight | Iterable[AccessRight])`

An access mask, built or given as right symbols or native bits. A subtype such as winreg.AccessMask is accepted too.

`AccessRight = (:DELETE: | :READ_CONTROL: | :WRITE_DAC: | :WRITE_OWNER: | :SYNCHRONIZE: | :STANDARD_RIGHTS_REQUIRED: | :STANDARD_RIGHTS_ALL: | :ACCESS_SYSTEM_SECURITY: | :MAXIMUM_ALLOWED: | :GENERIC_READ: | :GENERIC_WRITE: | :GENERIC_EXECUTE: | :GENERIC_ALL:)`

A symbol naming rights of an AccessMask.

Symbol	Meaning
`:DELETE:`	Delete the object
`:READ_CONTROL:`	Read its security descriptor, except the SACL
`:WRITE_DAC:`	Change its discretionary access-control list
`:WRITE_OWNER:`	Change its owner
`:SYNCHRONIZE:`	Synchronize access to the object
`:STANDARD_RIGHTS_REQUIRED:`	The standard rights required by most objects
`:STANDARD_RIGHTS_ALL:`	All standard rights
`:ACCESS_SYSTEM_SECURITY:`	Access its system access-control list
`:MAXIMUM_ALLOWED:`	Request the maximum rights allowed to the caller
`:GENERIC_READ:`	Request object-specific read access
`:GENERIC_WRITE:`	Request object-specific write access
`:GENERIC_EXECUTE:`	Request object-specific execute access
`:GENERIC_ALL:`	Request all object-specific access

`AceFlag = (:OBJECT_INHERIT: | :CONTAINER_INHERIT: | :NO_PROPAGATE_INHERIT: | :INHERIT_ONLY: | :INHERITED: | :CRITICAL: | :SUCCESSFUL_ACCESS: | :FAILED_ACCESS:)`

A symbol naming a flag of an AceFlags.

The trust-protected-filter flag occupies the same bit as :SUCCESSFUL_ACCESS: and has no symbol of its own. Read it from an access-filter entry's trust_protected_filter.

ace and the Ace constructor set the outcome flags from their own successful and failed arguments.

Symbol	Meaning
`:OBJECT_INHERIT:`	Non-container child objects inherit the entry
`:CONTAINER_INHERIT:`	Container child objects inherit the entry
`:NO_PROPAGATE_INHERIT:`	Inherited copies stop propagating after one generation
`:INHERIT_ONLY:`	The entry applies only through inheritance
`:INHERITED:`	The entry was inherited
`:CRITICAL:`	The entry is critical and cannot be removed
`:SUCCESSFUL_ACCESS:`	An audit or alarm entry selects successful access
`:FAILED_ACCESS:`	An audit or alarm entry selects failed access

`AceFlagsSpec = (AceFlags | Int | AceFlag | Iterable[AceFlag])`

ACE header flags, built or given as flag symbols or native bits.

AceSpec = (Ace | Dict[{allow: SidSpec, mask: AccessMaskSpec, ?flags: AceFlagsSpec, ?object_type: uuid.Guid | Str | Bin, ?inherited_object_type: uuid.Guid | Str | Bin, ?callback: Bool, ?application_data: Bin}] | Dict[{deny: SidSpec, mask: AccessMaskSpec, ?flags: AceFlagsSpec, ?object_type: uuid.Guid | Str | Bin, ?inherited_object_type: uuid.Guid | Str | Bin, ?callback: Bool, ?application_data: Bin}] | Dict[{audit: SidSpec, mask: AccessMaskSpec, ?flags: AceFlagsSpec, ?object_type: uuid.Guid | Str | Bin, ?inherited_object_type: uuid.Guid | Str | Bin, ?callback: Bool, ?application_data: Bin, ?successful: Bool, ?failed: Bool}])

An ACE, built or given as a dictionary.

A dictionary names its trustee under exactly one of allow:, deny:, or audit:, and takes the other arguments of ace as keys.

$
  allow: :BUILTIN_ADMINISTRATORS:
  mask: :GENERIC_ALL:
  flags: [:OBJECT_INHERIT:, :CONTAINER_INHERIT:]

AceType = (:ACCESS_ALLOWED: | :ACCESS_DENIED: | :SYSTEM_AUDIT: | :SYSTEM_ALARM: | :ACCESS_ALLOWED_COMPOUND: | :ACCESS_ALLOWED_OBJECT: | :ACCESS_DENIED_OBJECT: | :SYSTEM_AUDIT_OBJECT: | :SYSTEM_ALARM_OBJECT: | :ACCESS_ALLOWED_CALLBACK: | :ACCESS_DENIED_CALLBACK: | :ACCESS_ALLOWED_CALLBACK_OBJECT: | :ACCESS_DENIED_CALLBACK_OBJECT: | :SYSTEM_AUDIT_CALLBACK: | :SYSTEM_ALARM_CALLBACK: | :SYSTEM_AUDIT_CALLBACK_OBJECT: | :SYSTEM_ALARM_CALLBACK_OBJECT: | :SYSTEM_MANDATORY_LABEL: | :SYSTEM_RESOURCE_ATTRIBUTE: | :SYSTEM_SCOPED_POLICY_ID: | :SYSTEM_PROCESS_TRUST_LABEL: | :SYSTEM_ACCESS_FILTER: | :UNKNOWN:)

A native ACE type, or :UNKNOWN: for an unrecognized type code.

Code	Symbol
0	`:ACCESS_ALLOWED:`
1	`:ACCESS_DENIED:`
2	`:SYSTEM_AUDIT:`
3	`:SYSTEM_ALARM:`
4	`:ACCESS_ALLOWED_COMPOUND:`
5	`:ACCESS_ALLOWED_OBJECT:`
6	`:ACCESS_DENIED_OBJECT:`
7	`:SYSTEM_AUDIT_OBJECT:`
8	`:SYSTEM_ALARM_OBJECT:`
9	`:ACCESS_ALLOWED_CALLBACK:`
10	`:ACCESS_DENIED_CALLBACK:`
11	`:ACCESS_ALLOWED_CALLBACK_OBJECT:`
12	`:ACCESS_DENIED_CALLBACK_OBJECT:`
13	`:SYSTEM_AUDIT_CALLBACK:`
14	`:SYSTEM_ALARM_CALLBACK:`
15	`:SYSTEM_AUDIT_CALLBACK_OBJECT:`
16	`:SYSTEM_ALARM_CALLBACK_OBJECT:`
17	`:SYSTEM_MANDATORY_LABEL:`
18	`:SYSTEM_RESOURCE_ATTRIBUTE:`
19	`:SYSTEM_SCOPED_POLICY_ID:`
20	`:SYSTEM_PROCESS_TRUST_LABEL:`
21	`:SYSTEM_ACCESS_FILTER:`

`AclRevision = (:BASIC: | :DIRECTORY_SERVICE:)`

A named ACL revision. A native revision number is accepted wherever one of these is.

`AclSpec = (Acl | Iterable[AceSpec] | Dict[{...AceSpec, ?revision: AclRevision | Int}])`

An ACL, built or given as its entries in packet order.

A dictionary holds the entries positionally and may add a revision: key.

$
  revision: :DIRECTORY_SERVICE:
  - allow: $group.sid
    mask: :GENERIC_ALL:
    object_type: $schema_guid

`IdentifierAuthority = (:NULL: | :WORLD: | :LOCAL: | :CREATOR: | :NON_UNIQUE: | :NT: | :RESOURCE_MANAGER: | :APP_PACKAGE: | :MANDATORY_LABEL: | :SCOPED_POLICY: | :AUTHENTICATION: | :PROCESS_TRUST:)`

The identifier authority of a SID.

Symbol	Authority
`:NULL:`	Null
`:WORLD:`	World
`:LOCAL:`	Local
`:CREATOR:`	Creator
`:NON_UNIQUE:`	Non-unique
`:NT:`	NT
`:RESOURCE_MANAGER:`	Resource manager
`:APP_PACKAGE:`	Application package
`:MANDATORY_LABEL:`	Mandatory label
`:SCOPED_POLICY:`	Scoped policy ID
`:AUTHENTICATION:`	Authentication
`:PROCESS_TRUST:`	Process trust

`SecDescControlFlag = (:OWNER_DEFAULTED: | :GROUP_DEFAULTED: | :DACL_PRESENT: | :DACL_DEFAULTED: | :SACL_PRESENT: | :SACL_DEFAULTED: | :DACL_AUTO_INHERIT_REQUIRED: | :SACL_AUTO_INHERIT_REQUIRED: | :DACL_AUTO_INHERITED: | :SACL_AUTO_INHERITED: | :DACL_PROTECTED: | :SACL_PROTECTED: | :RM_CONTROL_VALID: | :SELF_RELATIVE:)`

A symbol naming a flag of a SecDescControl.

Symbol	Meaning
`:OWNER_DEFAULTED:`	Owner supplied by a default method
`:GROUP_DEFAULTED:`	Group supplied by a default method
`:DACL_PRESENT:`	DACL present
`:DACL_DEFAULTED:`	DACL supplied by a default method
`:SACL_PRESENT:`	SACL present
`:SACL_DEFAULTED:`	SACL supplied by a default method
`:DACL_AUTO_INHERIT_REQUIRED:`	DACL requires inheritance processing
`:SACL_AUTO_INHERIT_REQUIRED:`	SACL requires inheritance processing
`:DACL_AUTO_INHERITED:`	DACL was automatically inherited
`:SACL_AUTO_INHERITED:`	SACL was automatically inherited
`:DACL_PROTECTED:`	DACL blocks inheritable ACEs
`:SACL_PROTECTED:`	SACL blocks inheritable ACEs
`:RM_CONTROL_VALID:`	Resource-manager control byte valid
`:SELF_RELATIVE:`	Descriptor uses self-relative storage

`SecDescSpec = (SecDesc | Bin | Dict[{?owner: SidSpec | nil, ?group: SidSpec | nil, ?dacl: AclSpec | nil, ?sacl: AclSpec | nil, ?owner_defaulted: Bool, ?group_defaulted: Bool, ?dacl_present: Bool, ?dacl_defaulted: Bool, ?dacl_auto_inherit_required: Bool, ?dacl_auto_inherited: Bool, ?dacl_protected: Bool, ?sacl_present: Bool, ?sacl_defaulted: Bool, ?sacl_auto_inherit_required: Bool, ?sacl_auto_inherited: Bool, ?sacl_protected: Bool, ?rm_control: Int | nil}])`

A security descriptor, built, given as a self-relative packet, or given as a dictionary of the component arguments of sec_desc.

`SecInfoComponent = (:OWNER: | :GROUP: | :DACL: | :SACL: | :ALL:)`

A symbol naming components of a SecInfo.

Symbol	Component
`:OWNER:`	Owner SID
`:GROUP:`	Primary group SID
`:DACL:`	Discretionary ACL
`:SACL:`	System ACL
`:ALL:`	All supported components

`SidNameUse = (:USER: | :GROUP: | :DOMAIN: | :ALIAS: | :WELL_KNOWN_GROUP: | :DELETED_ACCOUNT: | :INVALID: | :UNKNOWN: | :COMPUTER: | :LABEL: | :LOGON_SESSION:)`

How Windows classifies a resolved SID.

Value	Meaning
`:USER:`	User SID
`:GROUP:`	Group SID
`:DOMAIN:`	Domain SID
`:ALIAS:`	Alias SID
`:WELL_KNOWN_GROUP:`	Well-known group SID
`:DELETED_ACCOUNT:`	Deleted account SID
`:INVALID:`	Invalid SID
`:UNKNOWN:`	SID of an unknown type
`:COMPUTER:`	Computer SID
`:LABEL:`	Mandatory integrity label SID
`:LOGON_SESSION:`	Logon session SID

`SidSpec = (Sid | Str | Bin | WellKnownSid)`

A SID, built or spelled as its canonical string, its native packet, or a well-known SID.

`TokenGroupAttribute = (:MANDATORY: | :ENABLED_BY_DEFAULT: | :ENABLED: | :OWNER: | :USE_FOR_DENY_ONLY: | :INTEGRITY: | :INTEGRITY_ENABLED: | :RESOURCE: | :LOGON_ID:)`

A symbol naming an attribute of a TokenGroupAttributes.

Symbol	Attribute
`:MANDATORY:`	Mandatory group
`:ENABLED_BY_DEFAULT:`	Enabled by default
`:ENABLED:`	Enabled
`:OWNER:`	Eligible as an object owner
`:USE_FOR_DENY_ONLY:`	Used only for deny checks
`:INTEGRITY:`	Integrity SID
`:INTEGRITY_ENABLED:`	Integrity SID enabled
`:RESOURCE:`	Resource group
`:LOGON_ID:`	Logon-session identifier

WellKnownSid = (:NULL: | :EVERYONE: | :LOCAL: | :CONSOLE_LOGON: | :CREATOR_OWNER: | :CREATOR_GROUP: | :OWNER_RIGHTS: | :DIALUP: | :NETWORK: | :BATCH: | :INTERACTIVE: | :SERVICE: | :ANONYMOUS: | :PRINCIPAL_SELF: | :AUTHENTICATED_USERS: | :RESTRICTED_CODE: | :REMOTE_INTERACTIVE_LOGON: | :THIS_ORGANIZATION: | :LOCAL_SYSTEM: | :LOCAL_SERVICE: | :NETWORK_SERVICE: | :LOCAL_ACCOUNT: | :LOCAL_ACCOUNT_ADMINISTRATOR: | :BUILTIN_ADMINISTRATORS: | :BUILTIN_USERS: | :BUILTIN_GUESTS: | :BUILTIN_POWER_USERS: | :BUILTIN_BACKUP_OPERATORS: | :BUILTIN_REMOTE_DESKTOP_USERS: | :BUILTIN_REMOTE_MANAGEMENT_USERS: | :ALL_APPLICATION_PACKAGES: | :ALL_RESTRICTED_APPLICATION_PACKAGES: | :UNTRUSTED_LABEL: | :LOW_LABEL: | :MEDIUM_LABEL: | :MEDIUM_PLUS_LABEL: | :HIGH_LABEL: | :SYSTEM_LABEL:)

A SID that is the same on every Windows installation, so naming one takes no lookup.

SIDs that are relative to a domain or a machine, such as Domain Admins (S-1-5-21-<domain>-512) or the local Administrator account, have no symbol: resolving one requires querying the system. The SDDL column is the two-letter alias the same SID has in an SDDL string, for readers porting one; those aliases are not accepted as symbols.

Symbol	SID	SDDL	Account or group
`:NULL:`	`S-1-0-0`		Null SID
`:EVERYONE:`	`S-1-1-0`	`WD`	Everyone
`:LOCAL:`	`S-1-2-0`		Local logon
`:CONSOLE_LOGON:`	`S-1-2-1`		Console logon
`:CREATOR_OWNER:`	`S-1-3-0`	`CO`	Creator owner
`:CREATOR_GROUP:`	`S-1-3-1`	`CG`	Creator group
`:OWNER_RIGHTS:`	`S-1-3-4`	`OW`	Owner rights
`:DIALUP:`	`S-1-5-1`		Dialup
`:NETWORK:`	`S-1-5-2`	`NU`	Network logon
`:BATCH:`	`S-1-5-3`	`BU`	Batch logon
`:INTERACTIVE:`	`S-1-5-4`	`IU`	Interactive logon
`:SERVICE:`	`S-1-5-6`	`SU`	Service logon
`:ANONYMOUS:`	`S-1-5-7`	`AN`	Anonymous logon
`:PRINCIPAL_SELF:`	`S-1-5-10`	`PS`	Principal self
`:AUTHENTICATED_USERS:`	`S-1-5-11`	`AU`	Authenticated users
`:RESTRICTED_CODE:`	`S-1-5-12`	`RC`	Restricted code
`:REMOTE_INTERACTIVE_LOGON:`	`S-1-5-14`		Remote interactive logon
`:THIS_ORGANIZATION:`	`S-1-5-15`		This organization
`:LOCAL_SYSTEM:`	`S-1-5-18`	`SY`	Local system
`:LOCAL_SERVICE:`	`S-1-5-19`	`LS`	Local service
`:NETWORK_SERVICE:`	`S-1-5-20`	`NS`	Network service
`:LOCAL_ACCOUNT:`	`S-1-5-113`		Any local account
`:LOCAL_ACCOUNT_ADMINISTRATOR:`	`S-1-5-114`		Local account in Administrators
`:BUILTIN_ADMINISTRATORS:`	`S-1-5-32-544`	`BA`	BUILTIN\Administrators
`:BUILTIN_USERS:`	`S-1-5-32-545`	`BU`	BUILTIN\Users
`:BUILTIN_GUESTS:`	`S-1-5-32-546`	`BG`	BUILTIN\Guests
`:BUILTIN_POWER_USERS:`	`S-1-5-32-547`	`PU`	BUILTIN\Power Users
`:BUILTIN_BACKUP_OPERATORS:`	`S-1-5-32-551`	`BO`	BUILTIN\Backup Operators
`:BUILTIN_REMOTE_DESKTOP_USERS:`	`S-1-5-32-555`	`RD`	BUILTIN\Remote Desktop Users
`:BUILTIN_REMOTE_MANAGEMENT_USERS:`	`S-1-5-32-580`	`RM`	BUILTIN\Remote Management Users
`:ALL_APPLICATION_PACKAGES:`	`S-1-15-2-1`	`AC`	All application packages
`:ALL_RESTRICTED_APPLICATION_PACKAGES:`	`S-1-15-2-2`		All restricted application packages
`:UNTRUSTED_LABEL:`	`S-1-16-0`		Untrusted integrity level
`:LOW_LABEL:`	`S-1-16-4096`	`LW`	Low integrity level
`:MEDIUM_LABEL:`	`S-1-16-8192`	`ME`	Medium integrity level
`:MEDIUM_PLUS_LABEL:`	`S-1-16-8448`	`MP`	Medium-plus integrity level
`:HIGH_LABEL:`	`S-1-16-12288`	`HI`	High integrity level
`:SYSTEM_LABEL:`	`S-1-16-16384`	`SI`	System integrity level

Functions

`ace :mask … -> Ace`

Constructs an Ace from declarative arguments.

Exactly one of allow, deny, or audit names the trustee.

Parameters

Name	Type	Description
`:allow?`	`SidSpec`	Trustee of an access-allowed entry.
`:deny?`	`SidSpec`	Trustee of an access-denied entry.
`:audit?`	`SidSpec`	Trustee of a system-audit entry.
`:mask`	`AccessMaskSpec`	Access mask.
`:flags?`	`AceFlagsSpec`	ACE header flags, other than the audit outcomes.
`:object_type?`	`(uuid.Guid \| Str \| Bin)`	Object type, making this an object entry.
`:inherited_object_type?`	`(uuid.Guid \| Str \| Bin)`	Inherited object type, making this an object entry.
`:callback?`	`Bool`	Build a callback entry.
`:application_data?`	`Bin`	Trailing application data, zero-padded to 32-bit alignment.
`:successful?`	`Bool`	Audit successful access.
`:failed?`	`Bool`	Audit failed access.

Errors

ValueError if zero or several trustees are given, if an audit entry has no outcome, or if successful or failed is given for an allow or deny entry.

Example

let entry = ace
  deny: :EVERYONE:
  mask: :GENERIC_WRITE:

`acl ...aces … -> Acl`

Constructs an Acl from entries and entry dictionaries.

Parameters

Name	Type	Description
`:revision?`	`(AclRevision \| Int)`	Native ACL revision. Defaults to the lowest revision the entries allow.
`...aces`	`AceSpec`	Entries in packet order, spread with `...` to pass a collection.

Example

let dacl = acl
  - allow: :LOCAL_SYSTEM:
    mask: :GENERIC_ALL:
  - allow: :BUILTIN_ADMINISTRATORS:
    mask: :GENERIC_ALL:

`sec_desc … -> SecDesc`

Constructs a SecDesc from a descriptor, components, or both.

Given both, the components amend desc the way SecDesc.with does. The update_sec_desc functions of other modules take the same arguments.

Parameters

Name	Type	Description
`desc?`	`SecDescSpec`	Descriptor to start from.
`:owner?`	`(SidSpec \| nil)`	Owner, or `nil` for an absent owner.
`:group?`	`(SidSpec \| nil)`	Primary group, or `nil` for an absent group.
`:dacl?`	`(AclSpec \| nil)`	Discretionary ACL, or `nil` for a present null ACL.
`:sacl?`	`(AclSpec \| nil)`	System ACL, or `nil` for a present null ACL.
`:owner_defaulted?`	`Bool`	Owner defaulted flag.
`:group_defaulted?`	`Bool`	Group defaulted flag.
`:dacl_present?`	`Bool`	DACL presence. `false` clears the DACL of `desc`.
`:dacl_defaulted?`	`Bool`	DACL defaulted flag.
`:dacl_auto_inherit_required?`	`Bool`	DACL inheritance request.
`:dacl_auto_inherited?`	`Bool`	DACL inherited flag.
`:dacl_protected?`	`Bool`	DACL protection.
`:sacl_present?`	`Bool`	SACL presence. `false` clears the SACL of `desc`.
`:sacl_defaulted?`	`Bool`	SACL defaulted flag.
`:sacl_auto_inherit_required?`	`Bool`	SACL inheritance request.
`:sacl_auto_inherited?`	`Bool`	SACL inherited flag.
`:sacl_protected?`	`Bool`	SACL protection.
`:rm_control?`	`(Int \| nil)`	Resource-manager control byte, or `nil` to clear it.

Errors

ValueError if neither a descriptor nor any component is given.

Example

let descriptor = sec_desc
  owner: :BUILTIN_ADMINISTRATORS:
  dacl_protected: true
  dacl:
    - allow: :LOCAL_SYSTEM:
      mask: :GENERIC_ALL:

let unprotected = sec_desc $descriptor dacl_protected: false

`token_info() -> TokenInfo`

Returns Windows token information captured for the active VFS context.

Errors

UnsupportedError if the active VFS target is Unix.

Example

if token_info().is_elevated
  echo elevated