NAME

Win32::Elevate - Perl module for gaining higher access privilege

SYNOPSIS

  use Win32::Elevate;
  
  # Gaining NT AUTHORITY\SYSTEM privilege to access files and registry
  # entries locked away from normal users
  Win32::Elevate::BecomeSystem();
  
  # Some files and especially registry entries are not even acessible
  # by SYSTEM. We need TrustedInstaller privilege for that.
  Win32::Elevate::BecomeTI();
  
  # Do some totally not shady stuff…
  
  # Done! Go back to user context.
  Win32::Elevate::RevertToSelf();

DESCRIPTION

The purpose of this module is to provide a couple of functions to access files and registry entries to which not even an elevated administrative user has access to. For this to work, the current process already needs to have elevated permissions.

WARNING! If you don't know, what you are doing, this can obviously be fatally dangerous, such as an unbootable system. So do your research and, especially, test your code thoroughly.

Functions

Win32::Elevate::BecomeSystem()

Elevates the first thread of the current process to gain NT AUTHORITY/SYSTEM privilege.

Returns a positive value on success. On faliure, it returns 0 and the thread is not altered.

Win32::Elevate::BecomeTI()

Elevates the first thread of the current process to gain NT SERVICE/TrustedInstaller privilege.

Returns a positive value on success. On faliure, it returns 0 and the current thread is not altered.

Win32::Elevate::RevertToSelf()

Undoes the priviledge changes made by Win32::Elevate::BecomeSystem() and/or Win32::Elevate::BecomeTI(). The current thread reverts to the same privilege as before any of these two functions were called.

Returns a positive value on success. On faliure, it returns 0 and the current thread is not altered.

Error Checking

You can check $^E or use Win32::FormatMessage( Win32::GetLastError() ) to get a descriptive error, but it might not be very informative. The C code calls several Win32 APIs. Since $^E is set to the latest API call, you won't know where it went bang!

CAVEATS

Obviously, this module only works on Windows. Also, it only works on the first thread of the current process. So you cannot spawn another thread and expect it to have the same privileges…

This module is tested on Windows 7 and 10.

UNDER THE HOOD

This module uses well known security design shortcomings in the Win32 API to gain privilege usually reserved for system processes. In short, a process running as an elevated user who is a member of the Administrator group can obtain SeDebugPrivilege. This in turn allows that process to copy and modify access tokens of system processes and use such a token to impersonate its access rights. Check the links below for more in-depth information.

SEE ALSO

https://www.tiraniddo.dev/2017/08/the-art-of-becoming-trustedinstaller.html

https://posts.specterops.io/understanding-and-defending-against-access-token-theft-finding-alternatives-to-winlogon-exe-80696c8a73b

https://github.com/lab52io/StopDefender. The C code of this module is mostly adapted from this program.

BUGS

The issue tracker is located on github.

SOURCE

The source repository can be found on github.

AUTHOR

Daniel Just

COPYRIGHT AND LICENSE

Copyright (C) 2021 by Daniel Just

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html