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
`AccessFilterAce`	Inspects a system access filter entry.
`AccessMask`	Generic Windows object access rights.
`Ace`	A Windows access-control entry, with its header and binary form.
`AceFlags`	Flags stored in an ACE header.
`Acl`	Immutable view of a native Windows access-control list.
`CommonAce`	Inspects a common qualified entry.
`CustomAce`	Preserves an uninterpreted entry, including unknown and compound kinds.
`KnownAce`	Inspects an entry with a trustee and access mask.
`MandatoryLabelAce`	Inspects a mandatory integrity label entry.
`ObjectAce`	Inspects an object-specific qualified entry.
`ProcessTrustLabelAce`	Inspects a process trust label entry.
`QualifiedAce`	Inspects an allow, deny, audit, or alarm entry, including callback forms.
`ResourceAttributeAce`	Inspects a resource attribute entry.
`ScopedPolicyIdAce`	Inspects a scoped policy ID entry.
`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.
`AceQualifier`	Qualifier of an access-control entry.
`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 order.
`IdentifierAuthority`	The identifier authority of a SID.
`SecDescControlFlag`	A symbol naming a flag of a `SecDescControl`.
`SecDescOptions[S = SidSpec, A = AclSpec]`	The components and control flags of a security descriptor, as keyword arguments or dictionary items. `S` is what an owner or group may be given as, and `A` what an ACL may be given as: specs by default, built values where a `SecDesc` method requires them.
`SecDescSpec`	A security descriptor, built, given in self-relative binary form, or given as a dictionary of `SecDescOptions`.
`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 binary form, 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`

A symbol naming rights of an AccessMask.

Type	Description
`: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`

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, CommonAce, and ObjectAce set the outcome flags from their own successful and failed arguments.

Type	Description
`: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.

`AceQualifier = (:ALLOW: | :DENY: | :AUDIT: | :ALARM:)`

Qualifier of an access-control entry.

`AceSpec`

@let AceSpec = $
  | Ace
  | BaseDict $
      allow: SidSpec
      mask: AccessMaskSpec
      ?flags: AceFlagsSpec
      ?object_type: (uuid.Guid | Str | Bin)
      ?inherited_object_type: (uuid.Guid | Str | Bin)
      ?callback: Bool
      ?application_data: Bin
  | BaseDict $
      deny: SidSpec
      mask: AccessMaskSpec
      ?flags: AceFlagsSpec
      ?object_type: (uuid.Guid | Str | Bin)
      ?inherited_object_type: (uuid.Guid | Str | Bin)
      ?callback: Bool
      ?application_data: Bin
  | BaseDict $
      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`

@let 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`

@let AclSpec = $
  | Acl
  | Iterable[AceSpec]
  | BaseDict[{*AceSpec, ?revision: AclRevision | Int}]

An ACL, built or given as its entries in 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`

The identifier authority of a SID.

Type	Description
`: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`

A symbol naming a flag of a SecDescControl.

Type	Description
`: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

`SecDescOptions[S = SidSpec, A = AclSpec]`

The components and control flags of a security descriptor, as keyword arguments or dictionary items. S is what an owner or group may be given as, and A what an ACL may be given as: specs by default, built values where a SecDesc method requires them.

Item	Type	Description
`?owner`	`S \| nil`	Owner, or `nil` for an absent owner
`?group`	`S \| nil`	Primary group, or `nil` for an absent group
`?dacl`	`A \| nil`	Discretionary ACL, or `nil` for a present null ACL
`?sacl`	`A \| 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 an existing DACL
`?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 an existing SACL
`?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

`SecDescSpec = (SecDesc | Bin | BaseDict[{...SecDescOptions}])`

A security descriptor, built, given in self-relative binary form, or given as a dictionary of SecDescOptions.

`SecInfoComponent`

A symbol naming components of a SecInfo.

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

`SidNameUse`

How Windows classifies a resolved SID.

Type	Description
`: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 binary form, or a well-known SID.

`TokenGroupAttribute`

A symbol naming an attribute of a TokenGroupAttributes.

Type	Description
`: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`

@let 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`		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 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 ...options … -> 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.
`...options`	`SecDescOptions`	Components and control flags, amending `desc` if given.

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