sddl

README

sddl - Windows Security Descriptor Library and CLI Tool

A cross-platform Go library and command-line tool for working with Windows Security Descriptors, providing conversion between binary and SDDL (Security Descriptor Definition Language) string formats.

Features

• Convert between binary and SDDL string formats
• Read security descriptors directly from files on Windows systems
• Support for all Security Descriptor components:
  • Owner and Group SIDs
  • DACLs and SACLs
  • All standard ACE types
  • Inheritance flags
  • ACL control flags
• Translation of well-known SIDs to aliases (e.g., "SY" for SYSTEM)
• Translation of common access masks to symbolic form (e.g., "FA" for Full Access)
• Cross-platform library functionality
• Windows-specific features when available
• Pure Go implementation with minimal dependencies

CLI Tool Usage

The command-line tool provides several modes of operation:

Basic Usage

# Convert base64-encoded binary descriptor to SDDL string (reads from stdin, writes to stdout)
echo "AQAAgBQAAAAkAAAAAAAAABAAAAAQAAQACAAEABIAAAA=" | sddl -i binary -o string > output.txt

# Convert SDDL string to base64-encoded binary (reads from stdin, writes to stdout)
echo "O:SYG:SY" | sddl -i string -o binary > binary_output.txt

# Read security descriptors from files (Windows only, filenames from stdin)
echo "C:\Windows\notepad.exe" | sddl -file > security_descriptors.txt

Input/Output Formats

• -i format: Input format, either 'binary' (base64 encoded) or 'string' (SDDL)
• -o format: Output format, either 'binary' (base64 encoded) or 'string' (SDDL)
• -file: Process input as filenames and read their security descriptors (Windows only)
• -debug: Prints the result in a human-readable format (applies only when -o string is used)

Examples

# Convert binary to SDDL
echo "AQAAgBQAAAAkAAAAAAAAABAAAAAQAAQACAAEABIAAAA=" | sddl -i binary -o string
# Output: O:SYG:SY

# Convert SDDL to binary
echo "O:SYG:SY" | sddl -i string -o binary
# Output: AQAAgBQAAAAkAAAAAAAAABAAAAAQAAQACAAEABIAAAA=

# Get security descriptor from files (Windows only)
echo "C:\Windows\notepad.exe" | sddl -file -o string
# Output: O:SYG:BAD:(A;;FA;;;SY)

Processing Rules

• Reads input line by line from stdin
• Each line should contain either a single security descriptor or filename
• Empty lines are ignored
• Processing continues even if some lines fail
• Errors are reported to stderr with line numbers
• Results are written to stdout, one per line

Library Usage

Installation

go get github.com/cloudsoda/sddl

Basic Usage

import "github.com/cloudsoda/sddl"

// Parse binary security descriptor
sd, err := sddl.FromBinary(binaryData)
if err != nil {
    // Handle error
}
sddlString, err := sd.String()

// Parse SDDL string
sd, err := sddl.FromString("O:SYG:BAD:(A;;FA;;;SY)")
if err != nil {
    // Handle error
}
binaryData, err := sd.Binary()

Windows-Specific Features

// Windows only: Get security descriptor from file
sddlString, err := GetFileSDString("C:\\Windows\\notepad.exe")

// Windows only: Get binary security descriptor from file
base64Data, err := GetFileSecurityBase64("C:\\Windows\\notepad.exe")

SDDL Format

Security descriptors in SDDL format follow this structure:

O:owner_sidG:group_sidD:dacl_flagsS:sacl_flags

Components:

• Owner SID (O:): Specifies the owner
• Group SID (G:): Specifies the primary group
• DACL (D:): Discretionary Access Control List
• SACL (S:): System Access Control List

ACL Format

ACLs contain flags and a list of ACEs (Access Control Entries):

D:flags(ace1)(ace2)...(aceN)

ACL Flags:

• P: Protected
• AI: Auto-inherited
• AR: Auto-inherit required
• NO: No propagate inherit

ACE Format

Each ACE follows this format:

(ace_type;ace_flags;rights;object_guid;inherit_object_guid;account_sid)

Components:

• ace_type: Type of ACE (e.g., "A" for Allow, "D" for Deny)
• ace_flags: Inheritance flags (e.g., "CI" for Container Inherit)
• rights: Access rights (e.g., "FA" for Full Access)
• account_sid: Security identifier for the trustee

Error Handling

The library provides detailed error information for various scenarios:

• Invalid security descriptor structure
• Malformed SIDs
• Invalid ACL or ACE formats
• Base64 decoding errors
• File access errors (Windows-specific features)

Errors include context about where in the parsing process they occurred to aid in debugging.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Documentation

Index

• Variables
• type SecurityDescriptor
  • func FromBinary(data []byte) (*SecurityDescriptor, error)
  • func FromString(s string) (*SecurityDescriptor, error)
  • func (sd *SecurityDescriptor) Binary() []byte
  • func (sd *SecurityDescriptor) String() string
  • func (sd *SecurityDescriptor) StringIndent(margin int) string

Variables

var (
	ErrInvalidAuthority         = errors.New("invalid authority value")
	ErrInvalidRevision          = errors.New("invalid SID revision")
	ErrInvalidSIDFormat         = errors.New("invalid SID format")
	ErrInvalidSubAuthority      = errors.New("invalid sub-authority value")
	ErrMissingDomainInformation = errors.New("missing domain information")
	ErrMissingSubAuthorities    = errors.New("missing sub-authorities")
	ErrTooManySubAuthorities    = errors.New("too many sub-authorities")
)

Define common errors

Types

type SecurityDescriptor

type SecurityDescriptor struct {
	// contains filtered or unexported fields
}

SecurityDescriptor represents the Windows SECURITY_DESCRIPTOR structure.

A security descriptor is a data structure that contains the security information associated with a securable object, such as a file, registry key, or network share. It includes an owner SID, a primary group SID, a discretionary access control list (DACL) that specifies the access rights allowed or denied to specific users or groups, and a system access control list (SACL) that specifies the types of auditing that are to be generated for specific users or groups.

See:

• https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-dtyp/7d4dac05-9cef-4563-a058-f108abecce1d
• https://learn.microsoft.com/en-us/windows/win32/secauthz/security-descriptor-control

func FromBinary

func FromBinary(data []byte) (*SecurityDescriptor, error)

FromBinary takes a binary security descriptor in relative format (contiguous memory with offsets)

func FromString

func FromString(s string) (*SecurityDescriptor, error)

FromString parses a security descriptor string in SDDL format. The format is: "O:owner_sidG:group_sidD:dacl_flagsS:sacl_flags" where each component is optional.

Examples: - "O:SYG:BAD:(A;;FA;;;SY)" - Owner: SYSTEM, Group: BUILTIN\Administrators, DACL with full access for SYSTEM - "O:SYG:SYD:PAI(A;;FA;;;SY)" - Protected auto-inherited DACL - "O:SYG:SYD:(A;;FA;;;SY)S:(AU;SA;FA;;;SY)" - With both DACL and SACL

func (*SecurityDescriptor) Binary

func (sd *SecurityDescriptor) Binary() []byte

Binary converts a SecurityDescriptor structure to its binary representation in self-relative format. The binary format consists of: - Fixed part:

• Revision (1 byte)
• Sbz1 (1 byte, reserved)
• Control (2 bytes, little-endian)
• OwnerOffset (4 bytes, little-endian)
• GroupOffset (4 bytes, little-endian)
• SaclOffset (4 bytes, little-endian)
• DaclOffset (4 bytes, little-endian)

- Variable part (in canonical order):

• Owner SID
• Group SID
• SACL
• DACL

func (*SecurityDescriptor) String

func (sd *SecurityDescriptor) String() string

func (*SecurityDescriptor) StringIndent

func (sd *SecurityDescriptor) StringIndent(margin int) string

StringIndent returns a formatted string representation of the SecurityDescriptor with the specified indentation margin. It includes the control flags, owner, group, and ACLs (if present), each properly indented for better readability.

Parameters:

• margin: number of spaces to prepend to each line

Returns a multi-line string containing the formatted security descriptor components.