common

package
v0.61.0-rc.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 12, 2024 License: Apache-2.0 Imports: 20 Imported by: 0

Documentation

Overview

Package common contains helpers for Windows E2E tests

Index

Constants

View Source 
const (
	DELETE                   = 0x00010000
	READ_CONTROL             = 0x00020000
	WRITE_DAC                = 0x00040000
	WRITE_OWNER              = 0x00080000
	SYNCHRONIZE              = 0x00100000
	STANDARD_RIGHTS_REQUIRED = 0x000F0000
	STANDARD_RIGHTS_READ     = READ_CONTROL
	STANDARD_RIGHTS_WRITE    = READ_CONTROL
	STANDARD_RIGHTS_EXECUTE  = READ_CONTROL
	STANDARD_RIGHTS_ALL      = 0x001F0000
	SPECIFIC_RIGHTS_ALL      = 0x0000FFFF
	ACCESS_SYSTEM_SECURITY   = 0x01000000
	MAXIMUM_ALLOWED          = 0x02000000
	GENERIC_READ             = 0x80000000
	GENERIC_WRITE            = 0x40000000
	GENERIC_EXECUTE          = 0x20000000
	GENERIC_ALL              = 0x10000000
)

SECURITY_DESCRIPTOR_CONTROL flags

https://learn.microsoft.com/en-us/windows/win32/secauthz/security-descriptor-control

View Source 
const (
	FILE_READ_DATA        = 0x00000001
	FILE_READ_ATTRIBUTES  = 0x00000080
	FILE_READ_EA          = 0x00000008
	FILE_WRITE_DATA       = 0x00000002
	FILE_WRITE_ATTRIBUTES = 0x00000100
	FILE_WRITE_EA         = 0x00000010
	FILE_APPEND_DATA      = 0x00000004
	FILE_EXECUTE          = 0x00000020

	FILE_GENERIC_READ    = STANDARD_RIGHTS_READ | FILE_READ_DATA | FILE_READ_ATTRIBUTES | FILE_READ_EA | SYNCHRONIZE
	FILE_GENERIC_WRITE   = STANDARD_RIGHTS_WRITE | FILE_WRITE_DATA | FILE_WRITE_ATTRIBUTES | FILE_WRITE_EA | FILE_APPEND_DATA | SYNCHRONIZE
	FILE_GENERIC_EXECUTE = STANDARD_RIGHTS_EXECUTE | FILE_READ_ATTRIBUTES | FILE_EXECUTE | SYNCHRONIZE

	FILE_LIST_DIRECTORY   = FILE_READ_DATA
	FILE_CREATE_FILES     = FILE_WRITE_DATA
	FILE_ADD_SUBDIRECTORY = FILE_APPEND_DATA
	FILE_TRAVERSE         = FILE_EXECUTE
	FILE_DELETE_CHILD     = 0x00000040
)

Filesystem access rights

https://learn.microsoft.com/en-us/windows/win32/wmisdk/file-and-directory-access-rights-constants https://learn.microsoft.com/en-us/windows/win32/fileio/file-security-and-access-rights

View Source 
const (
	ChangePermissions            = WRITE_DAC
	ReadPermissions              = READ_CONTROL
	TakeOwnership                = WRITE_OWNER
	DeleteSubdirectoriesAndFiles = FILE_DELETE_CHILD

	// FileFullControl = 0x001F01FF
	FileFullControl = SYNCHRONIZE | TakeOwnership | ChangePermissions | ReadPermissions | DELETE | FILE_WRITE_ATTRIBUTES | FILE_READ_ATTRIBUTES | DeleteSubdirectoriesAndFiles | FILE_TRAVERSE | FILE_WRITE_EA | FILE_READ_EA | FILE_ADD_SUBDIRECTORY | FILE_CREATE_FILES | FILE_LIST_DIRECTORY
	// FileRead = 0x00020089
	FileRead = ReadPermissions | FILE_READ_ATTRIBUTES | FILE_READ_EA | FILE_LIST_DIRECTORY
	// ReadAndExecute = // 0x000200A9
	FileReadAndExecute = FileRead | FILE_TRAVERSE
	// Write = 0x00000116
	FileWrite = FILE_WRITE_ATTRIBUTES | FILE_WRITE_EA | FILE_ADD_SUBDIRECTORY | FILE_CREATE_FILES
	// Modify = 0x000301BF
	FileModify = FileWrite | FileReadAndExecute | DELETE
)

Filesystem access rights

https://learn.microsoft.com/en-us/dotnet/api/system.security.accesscontrol.filesystemrights

View Source 
const (
	KEY_CREATE_LINK        = 0x0020
	KEY_CREATE_SUB_KEY     = 0x0004
	KEY_ENUMERATE_SUB_KEYS = 0x0008
	KEY_EXECUTE            = KEY_READ
	KEY_NOTIFY             = 0x0010
	KEY_QUERY_VALUE        = 0x0001
	KEY_READ               = STANDARD_RIGHTS_READ | KEY_QUERY_VALUE | KEY_ENUMERATE_SUB_KEYS | KEY_NOTIFY
	KEY_SET_VALUE          = 0x0002
	KEY_WRITE              = STANDARD_RIGHTS_WRITE | KEY_SET_VALUE | KEY_CREATE_SUB_KEY
	KEY_ALL_ACCESS         = STANDARD_RIGHTS_REQUIRED | KEY_QUERY_VALUE | KEY_SET_VALUE | KEY_CREATE_SUB_KEY | KEY_ENUMERATE_SUB_KEYS | KEY_NOTIFY | KEY_CREATE_LINK
)

Registry access rights

https://learn.microsoft.com/en-us/windows/win32/sysinfo/registry-key-security-and-access-rights

View Source 
const (
	// specific access rights
	SERVICE_CHANGE_CONFIG        = 0x0002
	SERVICE_ENUMERATE_DEPENDENTS = 0x0008
	SERVICE_INTERROGATE          = 0x0080
	SERVICE_PAUSE_CONTINUE       = 0x0040
	SERVICE_QUERY_CONFIG         = 0x0001
	SERVICE_QUERY_STATUS         = 0x0004
	SERVICE_START                = 0x0010
	SERVICE_STOP                 = 0x0020
	SERVICE_USER_DEFINED_CONTROL = 0x0100

	SERVICE_GENERIC_READ = STANDARD_RIGHTS_READ | SERVICE_QUERY_CONFIG | SERVICE_QUERY_STATUS | SERVICE_INTERROGATE | SERVICE_ENUMERATE_DEPENDENTS

	// SERVICE_ALL_ACCESS = 0xF01FF
	SERVICE_ALL_ACCESS = STANDARD_RIGHTS_REQUIRED | SERVICE_QUERY_CONFIG | SERVICE_CHANGE_CONFIG | SERVICE_QUERY_STATUS | SERVICE_ENUMERATE_DEPENDENTS | SERVICE_START | SERVICE_STOP | SERVICE_PAUSE_CONTINUE | SERVICE_INTERROGATE | SERVICE_USER_DEFINED_CONTROL
)

Service access rights

https://learn.microsoft.com/en-us/windows/win32/services/service-security-and-access-rights

View Source 
const (
	InheritanceFlagsNone      = 0
	InheritanceFlagsContainer = 1
	InheritanceFlagsObject    = 2
)

Inheritance flags

https://learn.microsoft.com/en-us/dotnet/api/system.security.accesscontrol.inheritanceflags

View Source 
const (
	PropagationFlagsNone        = 0
	PropagationFlagsInherit     = 1
	PropagationFlagsNoPropagate = 2
)

Propagation flags

https://learn.microsoft.com/en-us/dotnet/api/system.security.accesscontrol.propagationflags

View Source 
const (
	AccessControlTypeAllow = 0
	AccessControlTypeDeny  = 1
)

Access control types

https://learn.microsoft.com/en-us/dotnet/api/system.security.accesscontrol.accesscontroltype

View Source 
const (
	AuditFlagsNone    = 0
	AuditFlagsSuccess = 1
	AuditFlagsFailure = 2
)

Audit flags

https://learn.microsoft.com/en-us/dotnet/api/system.security.accesscontrol.auditflags?view=net-8.0

View Source 
const (

	// dwServiceType
	SERVICE_KERNEL_DRIVER       = 0x00000001
	SERVICE_FILE_SYSTEM_DRIVER  = 0x00000002
	SERVICE_WIN32_OWN_PROCESS   = 0x00000010
	SERVICE_WIN32_SHARE_PROCESS = 0x00000020

	// dwStartType
	SERVICE_SYSTEM_START = 1
	SERVICE_AUTO_START   = 2
	SERVICE_DEMAND_START = 3
	SERVICE_DISABLED     = 4
)

Service API constants https://learn.microsoft.com/en-us/windows/win32/api/winsvc/ns-winsvc-query_service_configa

View Source 
const (
	LocalSystemSID    = "S-1-5-18"
	AdministratorsSID = "S-1-5-32-544"
	EveryoneSID       = "S-1-1-0"
)

Well Known SIDs

https://learn.microsoft.com/en-us/windows/win32/secauthz/well-known-sids

View Source 
const (
	// RegistryFullControl = 0xF003F
	RegistryFullControl = TakeOwnership | ChangePermissions | ReadPermissions | DELETE | KEY_CREATE_LINK | KEY_NOTIFY | KEY_ENUMERATE_SUB_KEYS | KEY_CREATE_SUB_KEY | KEY_SET_VALUE | KEY_QUERY_VALUE
)

Registry access rights

https://learn.microsoft.com/en-us/dotnet/api/system.security.accesscontrol.registryrights

View Source 
const (
	// WERLocalDumpsRegistryKey is the registry key for Windows Error Reporting (WER) user-mode dumps
	WERLocalDumpsRegistryKey = `HKLM:SOFTWARE\Microsoft\Windows\Windows Error Reporting\LocalDumps`
)

Variables

This section is empty.

Functions

func AssertContainsEqualable added in v0.56.0 

func AssertContainsEqualable[T equalable[T]](t *testing.T, list []T, elem T, msgAndArgs ...any) bool

AssertContainsEqualable is a helper for AssertContainsFunc that works with types that implement the Equal method

func AssertContainsFunc added in v0.56.0 

func AssertContainsFunc[T any](t *testing.T, list []T, elem T, comp func(a, b T) bool, msgAndArgs ...any) bool

AssertContainsFunc is similar to the assert.Contains function, but it allows for a custom comparison function. It is also similar to slices.ContainsFunc, which it uses internally, but also provides a helpful error message in the style of the testify assert functions.

func AssertElementsMatchFunc added in v0.56.0 

func AssertElementsMatchFunc[T any](t *testing.T, expected, actual []T, comp func(a, b T) bool, msgAndArgs ...any) bool

AssertElementsMatchFunc is similar to the assert.ElementsMatch function, but it allows for a custom comparison function

func AssertEqualAccessSecurity added in v0.56.0 

func AssertEqualAccessSecurity(t *testing.T, path string, expected, actual ObjectSecurity)

AssertEqualAccessSecurity asserts that the access control settings for the expected and actual are equal.

Compares the owner, group, and access rules. Note that the order of the access rules is relevant when multiple rules apply to the same identity, but since this is not relevant for our use cases, we do not enforce the order of the rules in this function.

func AssertEqualableElementsMatch added in v0.56.0 

func AssertEqualableElementsMatch[T equalable[T]](t *testing.T, expected, actual []T, msgAndArgs ...any) bool

AssertEqualableElementsMatch is a helper for AssertElementsMatchFunc that works with types that implement the Equal method

func AssertNotContainsEqualable added in v0.56.0 

func AssertNotContainsEqualable[T equalable[T]](t *testing.T, list []T, elem T, msgAndArgs ...any) bool

AssertNotContainsEqualable is a helper for AssertNotContainsFunc that works with types that implement the Equal method

func AssertNotContainsFunc added in v0.56.0 

func AssertNotContainsFunc[T any](t *testing.T, list []T, elem T, comp func(a, b T) bool, msgAndArgs ...any) bool

AssertNotContainsFunc is the opposite of AssertContainsFunc. It checks that the element is not in the list.

func CleanDirectory added in v0.57.0 

func CleanDirectory(host *components.RemoteHost, dir string) error

CleanDirectory removes all children of a directory, but leaves the directory itself.

returns nil if the directory does not exist

func ClearEventLog added in v0.54.0 

func ClearEventLog(host *components.RemoteHost, logName string) error

ClearEventLog clears an event log

func ConvertUTF16ToUTF8 

func ConvertUTF16ToUTF8(content []byte) ([]byte, error)

ConvertUTF16ToUTF8 converts a byte slice from UTF-16 to UTF-8

UTF-16 little-endian (UTF-16LE) is the encoding standard in the Windows operating system. https://learn.microsoft.com/en-us/globalization/encoding/transformations-of-unicode-code-points

func DeleteRegistryKey added in v0.57.0 

func DeleteRegistryKey(host *components.RemoteHost, path string) error

DeleteRegistryKey deletes a registry key on the remote host

func DisableDefender 

func DisableDefender(host *components.RemoteHost) error

DisableDefender disables Windows Defender.

NOTE: Microsoft recently deprecated/removed/disabled the registry keys that were used to disable Windows Defender. This means the WinDefend service will still be running, but it should not interfere (as much). https://learn.microsoft.com/en-us/windows-hardware/customize/desktop/unattend/security-malware-windows-defender-disableantispyware

TODO: Microsoft "recommends" to uninstall defender, but this only works on Windows Server and it requires a reboot.

func DotSlashNameToLogonName 

func DotSlashNameToLogonName(host *components.RemoteHost, user string) (string, error)

DotSlashNameToLogonName converts a .\username to a hostname\username.

Simply stripping the .\ prefix is not sufficient because isolated named are ambiguous and may resolve to a domain account rather than a local account.

SCM uses .\ to specify the local machine when returning a local service account name.

func DownloadAllWERDumps added in v0.57.0 

func DownloadAllWERDumps(host *components.RemoteHost, dumpFolder string, outputPath string) ([]string, error)

DownloadAllWERDumps collects WER dumps from a folder on a remote host and saves them to a local folder

See DownloadWERDump for the naming convention used for the output files.

This function continues collecting dumps even if some of them fail to be collected, and returns an error with all the errors encountered.

func DownloadAllWERDumpsFunc added in v0.57.0 

func DownloadAllWERDumpsFunc(host *components.RemoteHost, dumpFolder string, outputPath string, f func(WERDumpFile) bool) ([]string, error)

DownloadAllWERDumpsFunc is like DownloadAllWERDumps, but allows to filter the dumps to collect

func DownloadFile 

func DownloadFile(host *components.RemoteHost, url string, destination string) error

DownloadFile downloads a file on the VM from a http/https URL

func DownloadWERDump added in v0.57.0 

func DownloadWERDump(host *components.RemoteHost, dump WERDumpFile, outputDir string) (string, error)

DownloadWERDump downloads a WER dump from a remote host and saves it to a local folder with the format <host address>-<dump file name>

func EnableWERGlobalDumps added in v0.57.0 

func EnableWERGlobalDumps(host *components.RemoteHost, dumpFolder string) error

EnableWERGlobalDumps enables Windows Error Reporting (WER) dumps for all applications

This function creates a folder to store the dumps and sets the registry keys to enable WER dumps. ACLs are set to allow everyone to write to the folder.

https://learn.microsoft.com/en-us/windows/win32/wer/collecting-user-mode-dumps

func ExportEventLog added in v0.54.0 

func ExportEventLog(host *components.RemoteHost, logName string, outputPath string) error

ExportEventLog exports an event log to a file

func FileNameFromPath added in v0.57.0 

func FileNameFromPath(path string) string

FileNameFromPath returns the last part of a path, which is the file name. Trailing slashes are removed before extracting the last element. Supports both backslashes and forward slashes, by returning the last part after the last backslash or forward slash.

func Filter added in v0.56.0 

func Filter[T any](list []T, filter func(T) bool) []T

Filter is a generic function that filters a list based on a provided filter function

func FilterRulesForIdentity added in v0.56.0 

func FilterRulesForIdentity[T AuthorizationRuleWithRights](acl []T, identity Identity) []T

FilterRulesForIdentity returns the rules that match the given identity

func FindPID 

func FindPID(host *components.RemoteHost, pattern string) ([]int, error)

FindPID returns a list of PIDs for processes that match the given pattern

func GetEventLogErrorsAndWarnings added in v0.54.0 

func GetEventLogErrorsAndWarnings(host *components.RemoteHost, logName string) (string, error)

GetEventLogErrorsAndWarnings returns a formatted list of errors and warnings from an event log useful for display/logging

func GetExpectedVersion 

func GetExpectedVersion(expectedVersion string) ([]string, error)

GetExpectedVersion gets the expected version from the most recent tag returns in the form of slice of strings, each element being a part of the version (major, minor, patch)

expectedVersion can be empty; if so, then it uses `git` to determine the expected version from the most recent tag. It also then assumes that git is in the path

func GetFileVersion 

func GetFileVersion(host *components.RemoteHost, remoteFileName string) ([]string, error)

GetFileVersion gets the file version information from the versioninfo resource of the specified file. It returns as a slice of strings, each element being part of the version (major, minor, patch, build)

// for the remote file, it uses the powershell version information command

func GetHostname 

func GetHostname(host *components.RemoteHost) (string, error)

GetHostname returns the hostname of the VM

func GetJoinedDomain 

func GetJoinedDomain(host *components.RemoteHost) (string, error)

GetJoinedDomain returns the domain that the host is joined to

func GetProductCodeByName 

func GetProductCodeByName(host *components.RemoteHost, name string) (string, error)

GetProductCodeByName returns the product code GUID for the given product name

func GetRegistryValue 

func GetRegistryValue(host *components.RemoteHost, path string, value string) (string, error)

GetRegistryValue returns a registry value from a remote host

func GetSIDForUser 

func GetSIDForUser(host *components.RemoteHost, user string) (string, error)

GetSIDForUser returns the SID for the given user.

user can be of the following forms

  • username
  • hostname\username
  • domain\username
  • username@domain

func GetServiceAccountName 

func GetServiceAccountName(host *components.RemoteHost, service string) (string, error)

GetServiceAccountName returns the account name that the service runs as

func GetServiceAliasSID 

func GetServiceAliasSID(alias string) (string, error)

GetServiceAliasSID returns the SID for a special SCM account alias

https://learn.microsoft.com/en-us/windows/win32/services/service-user-accounts

func GetServiceImagePath added in v0.54.0 

func GetServiceImagePath(host *components.RemoteHost, service string) (string, error)

GetServiceImagePath returns the image path (command line) of the service

func GetServicePID added in v0.54.0 

func GetServicePID(host *components.RemoteHost, service string) (int, error)

GetServicePID returns the PID of the service

func GetServiceStatus 

func GetServiceStatus(host *components.RemoteHost, service string) (string, error)

GetServiceStatus returns the status of the service

func GetTemporaryFile 

func GetTemporaryFile(host *components.RemoteHost) (string, error)

GetTemporaryFile returns a new temporary file path https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/new-temporaryfile?view=powershell-7.4

func GetUserForSID added in v0.56.0 

func GetUserForSID(host *components.RemoteHost, sid string) (string, error)

GetUserForSID returns the username for the given SID.

func GetUserRights 

func GetUserRights(host *components.RemoteHost) (map[string][]string, error)

GetUserRights returns a map of user rights to a list of users that have them

https://learn.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/user-rights-assignment

func GetUserRightsForUser 

func GetUserRightsForUser(host *components.RemoteHost, user string) ([]string, error)

GetUserRightsForUser returns a list of user rights for the given user

func GetWERGlobalDumpFolder added in v0.57.0 

func GetWERGlobalDumpFolder(host *components.RemoteHost) (string, error)

GetWERGlobalDumpFolder returns the folder where Windows Error Reporting (WER) dumps are stored as configured in the registry.

func InstallMSI 

func InstallMSI(host *components.RemoteHost, msiPath string, args string, logPath string) error

InstallMSI installs an MSI on the VM with the provided args and collects the install log

args may need to be escaped/quoted, see MsiExec() for details

func IsIdentityLocalSystem added in v0.56.0 

func IsIdentityLocalSystem(i Identity) bool

IsIdentityLocalSystem Returns true if the identity is the local SYSTEM account

func IsKernelModeServiceType added in v0.54.0 

func IsKernelModeServiceType(serviceType int) bool

IsKernelModeServiceType returns true if the service is a kernel mode service

func IsProcessRunning 

func IsProcessRunning(host *components.RemoteHost, imageName string) (bool, error)

IsProcessRunning returns true if process is running

func IsTamperProtected 

func IsTamperProtected(host *components.RemoteHost) (bool, error)

IsTamperProtected returns true if Windows Defender is tamper protected. If true, then Windows Defender cannot be disabled programatically and must be disabled through the UI.

https://learn.microsoft.com/en-us/microsoft-365/security/defender-endpoint/prevent-changes-to-security-settings-with-tamper-protection

https://learn.microsoft.com/en-us/microsoft-365/security/defender-endpoint/manage-tamper-protection-individual-device

func IsUserModeServiceType added in v0.54.0 

func IsUserModeServiceType(serviceType int) bool

IsUserModeServiceType returns true if the service is a user mode service

func MakeDownLevelLogonName 

func MakeDownLevelLogonName(domain string, user string) string

MakeDownLevelLogonName joins a user and domain into a single string, e.g. DOMAIN\user

domain is converted to NetBIOS format per the MSDN definition.

If domain is empty then the user is returned as-is. Use caution in this case as the isolated name may be ambiguous.

https://learn.microsoft.com/en-us/windows/win32/secauthn/user-name-formats#down-level-logon-name

func MeasureCommand added in v0.56.0 

func MeasureCommand(host *components.RemoteHost, command string) (time.Duration, string, error)

MeasureCommand uses Measure-Command and returns time taken (in milliseconds), out, err

func MsiExec 

func MsiExec(host *components.RemoteHost, operation string, product string, args string, logPath string) error

MsiExec runs msiexec on the VM with the provided operation and args and collects the log

args may need to be escaped/quoted. The Start-Process ArgumentList parameter value is wrapped in single quotes. For example:

func NameToNetBIOSName 

func NameToNetBIOSName(name string) string

NameToNetBIOSName converts a given host or DNS name into a NetBIOS formatted name

Warning: This is not necessarily the actual NetBIOS name of the host, as it can be configured separately from the DNS name.

https://learn.microsoft.com/en-us/troubleshoot/windows-server/identity/naming-conventions-for-computer-domain-site-ou

func PutOrDownloadFile 

func PutOrDownloadFile(host *components.RemoteHost, url string, destination string) error

PutOrDownloadFile creates a file on the VM from a file/http URL

If the URL is a local file, it will be uploaded to the VM. If the URL is a remote file, it will be downloaded from the VM

func PutOrDownloadFileWithRetry added in v0.59.0 

func PutOrDownloadFileWithRetry(host *components.RemoteHost, url string, destination string, b backoff.BackOff) error

PutOrDownloadFileWithRetry is similar to PutOrDownloadFile but retries on download failure, local file copy is not retried.

func RegistryKeyExists added in v0.54.0 

func RegistryKeyExists(host *components.RemoteHost, path string) (bool, error)

RegistryKeyExists returns true if the registry key exists on the remote host

func RemoveLocalUser added in v0.54.0 

func RemoveLocalUser(host *components.RemoteHost, user string) error

RemoveLocalUser Removes a local user account NOTE: this does not remove the user profile, which without a reboot is probably locked by the system.

func RepairAllMSI 

func RepairAllMSI(host *components.RemoteHost, msiPath string, args string, logPath string) error

RepairAllMSI repairs an MSI with /fa on the VM and collects the repair log

/fa: a - forces all files to be reinstalled

args may need to be escaped/quoted, see MsiExec() for details

func RestartService 

func RestartService(host *components.RemoteHost, service string) error

RestartService restarts the service

func SecurityIdentifierEqual added in v0.56.0 

func SecurityIdentifierEqual(a SecurityIdentifier, b SecurityIdentifier) bool

SecurityIdentifierEqual returns true if the SIDs are equal. Names can be localized, ambiguous, or just be in different formats.

func SetServiceEnvironment added in v0.57.0 

func SetServiceEnvironment(host *components.RemoteHost, service string, env map[string]string) error

SetServiceEnvironment sets the environment variables for a service

func StartService 

func StartService(host *components.RemoteHost, service string) error

StartService starts the service

func StopService 

func StopService(host *components.RemoteHost, service string) error

StopService stops the service

func TrimTrailingSlashesAndLower added in v0.54.0 

func TrimTrailingSlashesAndLower(path string) string

TrimTrailingSlashesAndLower trims trailing slashes and lowercases the path for use in simple comparisons.

Some cases may require a more comprehensive comparison, which could be made by normalizing the path on the host via PowerShell, to support removing dot paths, resolving links, etc

func UninstallMSI 

func UninstallMSI(host *components.RemoteHost, msiPath string, args string, logPath string) error

UninstallMSI uninstalls an MSI on the VM and collects the uninstall log

func VerifyVersion 

func VerifyVersion(host *components.RemoteHost, remoteFileName, expectedVersion string) error

VerifyVersion takes a filename and an expected version and determines if the file matches the expected version.

Types

type AccessRule added in v0.56.0 

type AccessRule struct {
	AuthorizationRule
	Rights            int
	AccessControlType int
}

AccessRule represents a Windows access rule ACE

https://learn.microsoft.com/en-us/dotnet/api/system.security.accesscontrol.accessrule

func NewExplicitAccessRule added in v0.56.0 

func NewExplicitAccessRule(identity Identity, rights int, accessControlType int) AccessRule

NewExplicitAccessRule creates a new explicit AccessRule

Flags default to no inheritance, no no propagation

func NewExplicitAccessRuleWithFlags added in v0.56.0 

func NewExplicitAccessRuleWithFlags(identity Identity, rights int, accessControlType int, inheritanceFlags int, propagationFlags int) AccessRule

NewExplicitAccessRuleWithFlags creates a new AccessRule with the given flags

func NewInheritedAccessRule added in v0.56.0 

func NewInheritedAccessRule(identity Identity, rights int, accessControlType int) AccessRule

NewInheritedAccessRule creates a new inherited AccessRule

func NewInheritedAccessRuleWithFlags added in v0.56.0 

func NewInheritedAccessRuleWithFlags(identity Identity, rights int, accessControlType int, inheritanceFlags int, propagationFlags int) AccessRule

NewInheritedAccessRuleWithFlags creates a new inherited AccessRule with the given flags

func (AccessRule) Equal added in v0.56.0 

func (r AccessRule) Equal(other AccessRule) bool

Equal returns true if the rules are equal.

func (AccessRule) GetRights added in v0.56.0 

func (r AccessRule) GetRights() int

GetRights returns the rights for the access rule

func (AccessRule) IsAllow added in v0.56.0 

func (r AccessRule) IsAllow() bool

IsAllow returns true if the access rule is an allow rule

func (AccessRule) IsDeny added in v0.56.0 

func (r AccessRule) IsDeny() bool

IsDeny returns true if the access rule is a deny rule

type AuditRule added in v0.56.0 

type AuditRule struct {
	AuthorizationRule
	Rights     int
	AuditFlags int
}

AuditRule represents Windows audit rule ACE

https://learn.microsoft.com/en-us/dotnet/api/system.security.accesscontrol.auditrule

func (AuditRule) AuditFailure added in v0.56.0 

func (r AuditRule) AuditFailure() bool

AuditFailure returns true if failed access attempts are audited

func (AuditRule) AuditSuccess added in v0.56.0 

func (r AuditRule) AuditSuccess() bool

AuditSuccess returns true if successful access attempts are audited

func (AuditRule) Equal added in v0.56.0 

func (r AuditRule) Equal(other AuditRule) bool

Equal returns true if the rules are equal.

func (AuditRule) GetRights added in v0.56.0 

func (r AuditRule) GetRights() int

GetRights returns the rights for the audit rule

type AuthenticodeCertificate 

type AuthenticodeCertificate struct {
	Subject    string `json:"Subject"`
	Issuer     string `json:"Issuer"`
	Thumbprint string `json:"Thumbprint"`
}

AuthenticodeCertificate represents the certificate used to sign the file

type AuthenticodeSignature 

type AuthenticodeSignature struct {
	SignerCertificate AuthenticodeCertificate `json:"SignerCertificate"`
	Status            int                     `json:"Status"`
	StatusMessage     string                  `json:"StatusMessage"`
}

AuthenticodeSignature is the result of GetAuthenticodeSignature()

func GetAuthenticodeSignature 

func GetAuthenticodeSignature(host *components.RemoteHost, path string) (*AuthenticodeSignature, error)

GetAuthenticodeSignature returns the Authenticode signature of the file https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.security/get-authenticodesignature

func (*AuthenticodeSignature) Valid 

func (s *AuthenticodeSignature) Valid() bool

Valid returns true if the signature is valid.

type AuthorizationRule added in v0.56.0 

type AuthorizationRule struct {
	Identity         Identity
	InheritanceFlags int
	PropagationFlags int
	IsInherited      bool
}

AuthorizationRule represents the identity and inheritance flags for a Windows ACE

https://learn.microsoft.com/en-us/dotnet/api/system.security.accesscontrol.authorizationrule

func (AuthorizationRule) Equal added in v0.56.0 

func (r AuthorizationRule) Equal(other AuthorizationRule) bool

Equal returns true if the rules are equal.

See Identity.Equal for more information on how it is compared.

func (AuthorizationRule) GetAuthorizationRule added in v0.56.0 

func (r AuthorizationRule) GetAuthorizationRule() AuthorizationRule

GetAuthorizationRule returns the authorization rule, used to satisfy interfces when embedding in other structs

type AuthorizationRuleWithRights added in v0.56.0 

type AuthorizationRuleWithRights interface {
	GetAuthorizationRule() AuthorizationRule
	GetRights() int
}

AuthorizationRuleWithRights is an interface for an authorization rule with rights

type BoundPort 

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

BoundPort represents a port that is bound to a process

func ListBoundPorts 

func ListBoundPorts(host *components.RemoteHost) ([]*BoundPort, error)

ListBoundPorts returns a list of bound ports

func (*BoundPort) LocalAddress 

func (b *BoundPort) LocalAddress() string

LocalAddress returns the local address of the bound port

func (*BoundPort) LocalPort 

func (b *BoundPort) LocalPort() int

LocalPort returns the local port of the bound port

func (*BoundPort) PID 

func (b *BoundPort) PID() int

PID returns the PID of the bound port

func (*BoundPort) Process 

func (b *BoundPort) Process() string

Process returns the process name of the bound port

type EventLogEntry added in v0.56.0 

type EventLogEntry struct {
	ID           int
	Level        int
	ProviderName string
	LogName      string
	Message      string
	RecordID     int
	TimeCreated  string
}

EventLogEntry contains basic information from a Windows event log entry

func GetEventLogEntries added in v0.56.0 

func GetEventLogEntries(host *components.RemoteHost, logName string) ([]EventLogEntry, error)

GetEventLogEntries returns a list of event log entries

func GetEventLogEntriesFromProvider added in v0.56.0 

func GetEventLogEntriesFromProvider(host *components.RemoteHost, logName string, providerName string) ([]EventLogEntry, error)

GetEventLogEntriesFromProvider returns a list of event log entries from a specific provider

func GetEventLogEntriesWithFilterHashTable added in v0.56.0 

func GetEventLogEntriesWithFilterHashTable(host *components.RemoteHost, filterHashTable string) ([]EventLogEntry, error)

GetEventLogEntriesWithFilterHashTable returns a list of event log entries with a filter hash table

https://learn.microsoft.com/en-us/powershell/scripting/samples/creating-get-winevent-queries-with-filterhashtable

func GetEventLogErrorAndWarningEntries added in v0.56.0 

func GetEventLogErrorAndWarningEntries(host *components.RemoteHost, logName string) ([]EventLogEntry, error)

GetEventLogErrorAndWarningEntries returns a list of error and warning event log entries

type FileSystemSnapshot 

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

FileSystemSnapshot represents a snapshot of the system files that can be used to compare against later

func NewFileSystemSnapshot 

func NewFileSystemSnapshot(host *components.RemoteHost, pathsToIgnore []string) (*FileSystemSnapshot, error)

NewFileSystemSnapshot takes a snapshot of the system files that can be used to compare against later. The snapshot is overridden if it already exists.

func (*FileSystemSnapshot) Cleanup 

func (fs *FileSystemSnapshot) Cleanup() error

Cleanup removes the snapshot if it exists

func (*FileSystemSnapshot) CompareSnapshots 

func (fs *FileSystemSnapshot) CompareSnapshots(other *FileSystemSnapshot) (string, error)

CompareSnapshots compares two system file snapshots and returns a list of files that are missing in the second snapshot

func (*FileSystemSnapshot) Validate 

func (fs *FileSystemSnapshot) Validate() error

Validate ensures the snapshot file exists and is a reasonable size

type HostInfo 

type HostInfo struct {
	Hostname string
	Domain   string
	OSInfo   *OSInfo
}

HostInfo contains information about a Windows host, such as the hostname and version

func GetHostInfo 

func GetHostInfo(host *components.RemoteHost) (*HostInfo, error)

GetHostInfo returns HostInfo for the given VM

func (*HostInfo) IsDomainController 

func (h *HostInfo) IsDomainController() bool

IsDomainController returns true if the host is a domain controller

type Identity 

type Identity struct {
	Name string
	SID  string
}

Identity contains the name and SID of an identity (user or group)

func GetADGroupMembers 

func GetADGroupMembers(host *components.RemoteHost, group string) ([]Identity, error)

GetADGroupMembers returns the list of members of the given AD group

func GetIdentityForSID added in v0.56.0 

func GetIdentityForSID(sid string) Identity

GetIdentityForSID returns an Identity for the given SID. Does not fetch the name, see GetIdentityForSIDWithName.

func GetIdentityForSIDWithName added in v0.56.0 

func GetIdentityForSIDWithName(host *components.RemoteHost, sid string) (Identity, error)

GetIdentityForSIDWithName returns an Identity for the given SID with the name fetched from the host.

This is useful when the name is needed for display purposes. The name may be localized or ambiguous, and may not be unique.

func GetIdentityForUser added in v0.56.0 

func GetIdentityForUser(host *components.RemoteHost, user string) (Identity, error)

GetIdentityForUser returns the Identity for the given user.

func GetLocalGroupMembers 

func GetLocalGroupMembers(host *components.RemoteHost, group string) ([]Identity, error)

GetLocalGroupMembers returns the list of members of the given local group

func (Identity) Equal added in v0.56.0 

func (i Identity) Equal(other SecurityIdentifier) bool

Equal returns true if the SIDs are equal. Names can be localized, ambiguous, or just be in different formats.

func (Identity) GetName 

func (i Identity) GetName() string

GetName returns the name of the identity

func (Identity) GetSID 

func (i Identity) GetSID() string

GetSID returns the SID of the identity

type OSInfo 

type OSInfo struct {
	WindowsDirectory string `json:"WindowsDirectory"`
	Version          string `json:"Version"`
	SystemDrive      string `json:"SystemDrive"`
	SystemDirectory  string `json:"SystemDirectory"`
	ProductType      int    `json:"ProductType"`
	OSType           int    `json:"OSType"`
	OSProductSuite   int    `json:"OSProductSuite"`
	OSLanguage       int    `json:"OSLanguage"`
	Locale           string `json:"Locale"`
	BuildNumber      string `json:"BuildNumber"`
	Caption          string `json:"Caption"`
}

OSInfo contains a selection of values from: Get-WmiObject Win32_OperatingSystem https://learn.microsoft.com/en-us/windows/win32/cimwin32prov/win32-operatingsystem

func GetOSInfo 

func GetOSInfo(host *components.RemoteHost) (*OSInfo, error)

GetOSInfo returns OSInfo for the given VM

type ObjectSecurity added in v0.56.0 

type ObjectSecurity struct {
	Owner                   Identity
	Group                   Identity
	Access                  []AccessRule
	Audit                   []AuditRule
	SDDL                    string
	AreAccessRulesProtected bool
	AreAuditRulesProtected  bool
}

ObjectSecurity represents the security information for a Windows Object (e.g. file, directory, registry key)

https://learn.microsoft.com/en-us/dotnet/api/system.security.accesscontrol.nativeobjectsecurity

func GetNamedPipeSecurityInfo 

func GetNamedPipeSecurityInfo(host *components.RemoteHost, pipeName string) (ObjectSecurity, error)

GetNamedPipeSecurityInfo returns the security information for the given named pipe

  • Example pipe name: \\.\pipe\mypipe
  • Example pipe name: mypipe

func GetSecurityInfoForPath added in v0.56.0 

func GetSecurityInfoForPath(host *components.RemoteHost, path string) (ObjectSecurity, error)

GetSecurityInfoForPath returns the security information for the given path using Get-ACL

  • Example file path: C:\Windows\Temp\file.txt
  • Example registry path: HKLM:\SOFTWARE\Datadog

https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.security/get-acl

func GetServiceSecurityInfo added in v0.56.0 

func GetServiceSecurityInfo(host *components.RemoteHost, serviceName string) (ObjectSecurity, error)

GetServiceSecurityInfo returns the security information for the given service

func NewInheritSecurityInfo added in v0.56.0 

func NewInheritSecurityInfo(owner Identity, group Identity, access []AccessRule) ObjectSecurity

NewInheritSecurityInfo creates a new ObjectSecurity that can inherit access rules

func NewProtectedSecurityInfo added in v0.56.0 

func NewProtectedSecurityInfo(owner Identity, group Identity, access []AccessRule) ObjectSecurity

NewProtectedSecurityInfo creates a new ObjectSecurity with protected access rules (i.e. inheritance is disabled)

type SecurityIdentifier 

type SecurityIdentifier interface {
	GetName() string
	GetSID() string
}

SecurityIdentifier is an interface for objects that have a name and SID

type ServiceConfig 

type ServiceConfig struct {
	ServiceName        string
	DisplayName        string
	ImagePath          string
	StartType          int
	ServiceType        int
	Status             int
	UserName           string
	UserSID            string
	ServicesDependedOn []string `json:"-"`
}

ServiceConfig contains information about a Windows service

func GetServiceConfig 

func GetServiceConfig(host *components.RemoteHost, service string) (*ServiceConfig, error)

GetServiceConfig returns the configuration of the service

https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.management/get-service?view=powershell-7.4

func (*ServiceConfig) FetchUserSID 

func (s *ServiceConfig) FetchUserSID(host *components.RemoteHost) error

FetchUserSID fetches the SID for the service user

func (*ServiceConfig) UnmarshalJSON 

func (s *ServiceConfig) UnmarshalJSON(b []byte) error

UnmarshalJSON implements the yaml.Unmarshaler interface

type ServiceConfigMap 

type ServiceConfigMap map[string]*ServiceConfig

ServiceConfigMap maps a service name to a ServiceConfig

func GetEmptyServiceConfigMap 

func GetEmptyServiceConfigMap(services []string) ServiceConfigMap

GetEmptyServiceConfigMap returns a ServiceConfigMap with only the ServiceName set

func GetServiceConfigMap 

func GetServiceConfigMap(host *components.RemoteHost, services []string) (ServiceConfigMap, error)

GetServiceConfigMap returns a map of service names to service configuration

type WERDumpFile added in v0.57.0 

type WERDumpFile struct {
	// Path to the dump file
	Path string
	// FileName part of Path
	FileName string
	// Process ID, extracted from FileName
	PID string
	// Image name, extracted from FileName
	ImageName string
}

WERDumpFile represents a Windows Error Reporting (WER) dump file

func ListWERDumps added in v0.57.0 

func ListWERDumps(host *components.RemoteHost, dumpFolder string) ([]WERDumpFile, error)

ListWERDumps lists WER dumps in a folder on a remote host

Source Files

View all Source files

Directories

Path Synopsis
Package agent includes helpers related to the Datadog Agent on Windows
 Package agent includes helpers related to the Datadog Agent on Windows
installers/v2
Package installers processes the installers_v2.json file
 Package installers processes the installers_v2.json file
Package pipeline provides helper functions for working with the Gitlab pipeline
 Package pipeline provides helper functions for working with the Gitlab pipeline
Package powershell provides
 Package powershell provides

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.