Win32::Security::Recursor - Security recursion for named objects
Win32::Security::Recursor
use Win32::Security::Recursor; my $recursor = Win32::Security::Recursor::SE_FILE_OBJECT->new( payload => sub { my $self = shift; my($node_info, $cont_info) = @_; print $self->node_name($node_info)."\n"; } ); $recursor->recurse($ARGV[0]);
This module is designed to support scripts that need to recurse through a hierarchy of objects (i.e. a directory tree, registry hive, etc.), and interfacing with the security information on every node. There are a number of reasons this module was developed, instead of simply reusing File::Find.
File::Find
Applicability to multiple tree types. While not currently implemented, I tried to architect the interfaces and the internals so that it should be relatively simple to extend the code base to support the registry, Active Directory, and any other hierarchies of NamedObjects.
Applicability to permissions recursion. In particular, it is very common to compare the permissions on a node with the permissions on a parent node. To avoid performance-sapping duplication of effort, the system passes the payload both the information for the node and for its parent.
General performance improvements. Information is cached where appropriate (for instance, testing for whether a node is a container), thus reducing duplicate system calls. System calls were further optimized. For instance, it turns out that Win32::File::GetAttributes is over twice as fast as the built-in -d operator, at least under Perl 5.6.1 - this shaves roughly 0.3 ms per node on a Pent III Xeon 450 (or 30 seconds when scanning 100,000 files!), and even more given that it lets one test for JUNCTION points with almost no additional overhead.
Win32::File::GetAttributes
-d
Error handling. Error handling is passed through well defined interfaces, thus letting the developer choose how to display and/or record errors.
All of this comes at a price, however, and that is complexity. Some of that is because the problem itself is complex - objects fail to respond to API calls, JUNCTION points can complicate recursion, etc. Some of it is because the module was designed to be as flexible as possible, and so code was broken up into a wide variety of methods, thus making granual overriding possible. The module makes use of Class::Prototyped to support object-level method overriding without the need for explicit subclassing.
Class::Prototyped
This installs as part of Win32-Security. See Win32::Security::NamedObject for more information.
Win32-Security
Win32::Security::NamedObject
It depends upon the other Win32-Security modules and Class::Prototyped.
Win32-Security modules and Class::Prototyped.
The docs for this module are still under development. The documentation present is correct, but to really understand the module you need to look at the source.
There are subclasses of Win32::Security::Recursor for each type of supported Win32::Security::NamedObject (i.e. 'SE_FILE_OBJECT' for now - 'SE_REGISTRY_KEY' is not yet supported). The subclasses are responsible for implementing hierarchy specific behavior, such as enumerating child nodes, determining whether a node is a container, etc.
'SE_FILE_OBJECT'
'SE_REGISTRY_KEY'
new
The new method is entirely inherited from Class::Prototyped. A list of slot names and values may be passed if desired using the normal Class::Prototyped::addSlots syntax.
Class::Prototyped::addSlots
recurse
The recurse method is the heart of Win32::Security::Recursor. It accepts a single object name and recurses through the tree of objects rooted by that object. It does not use recursion, though, but rather a stack-based approach that flattens the recursion into a loop.
First, though, it creates an entirely new object to handle the call sequence. This object inherits from the object upon which recurse was called, and has a nodes slot that consists of an anonymous array of nodes remaining to be processed. Each node is a hash consisting of a name which stores the object-name in question, a parent which is a reference to the parent node, and keys which store cached responses for the various node information calls.
nodes
name
parent
The currently "active" node is always the last one on the array. Nodes are pushed onto the array in reverse order so that a depth-first search is effected.
Once the first node is on the array, basic flow through the loop looks like this:
Calls node_filternode on current node
node_filternode
Calls node_filternode to filter individual node. If node_filternode returns true, execution proceeds through the loop. The call to node_filternode traps die with an eval, so a die is treated like a false value. If the call fails or dies, then the node is popped off of the array and the loop restarted. This happens here to that node_filternode filters the nodes in the proper order so that any output is sorted appropriately.
die
eval
Calls payload on current node
payload
The call to payload is wrapped in an eval and any returned $@ is printed to STDERR if $self->debug() is true.
$@
STDERR
$self->debug()
Determines list of child nodes and pushes them onto the array
This whole procedure is wrapped in an eval. If any part of it fails, any returned $@ is printed to STDERR if $self->debug() is true and then the last node is popped off of the array. The code first calls node_iscontainer, and if false simply pops the last node off the array. Otherwise, node_enumchildren is called to build a list of child nodes (each of which has a parent that points to the current node). node_filterchildren is then called, which is responsible for ordering the child nodes as desired and for filtering out any nodes which wouldn't result in any output. Finally, the list of child nodes is reversed and used to replace the active node.
node_iscontainer
node_enumchildren
node_filterchildren
objectType
This returns the objectType for a given Recursor. Should be overridden by child classes.
debug
This defaults to true. Pass in "[qw(debug constant)] => 0," to new to turn debug off.
[qw(debug constant)] => 0,
Needs to be overridden to actually do anything!
node_getinfo
Used to get information about a node and/or the parent node. This accepts a list of "requests" and then returns the requested information. Each request consists of a pair of values. The first value should be either 'node', 'parent', or a node HASH. The second value should be either an info name or a reference to an array of info names. The permitted info names are:
'node'
'parent'
HASH
The node object name.
iscontainer
True if the node is a container object, false otherwise.
namedobject
Returns the Win32::Security::NamedObject object for this node.
dacl
Returns the Win32::Security::ACL object for the DACL of this node.
Win32::Security::ACL
ownerTrustee
Returns the owner as Trustee for this node.
ownerSid
Returns the owner as SID for this node.
container
Returns the name of the container that contains this object, if there is one.
The information is returned in a list in the order requested.
In order to make it easier to reuse some of my code, I have taken the liberty of putting some of my recursors into Win32::Security::Recursor.
Win32::Security::Recursor::SE_FILE_OBJECT::PermDump->new($options)
This takes a ref to an options hash and returns a recursor that implements the same behavior displayed by PermDump.pl. It takes an optional list of parameters that will be passed to Win32::Security::Recursor::SE_FILE_OBJECT->new so as to override or define new methods for the recursor.
PermDump.pl
Win32::Security::Recursor::SE_FILE_OBJECT->new
Options passable in the options hash are:
csv
dirsonly
inherited
owner
Toby Ovod-Everett, toby@ovod-everett.org
1 POD Error
The following errors were encountered while parsing the POD:
Unterminated C<...> sequence
To install Win32::Security::SID, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Win32::Security::SID
CPAN shell
perl -MCPAN -e shell install Win32::Security::SID
For more information on module installation, please visit the detailed CPAN module installation guide.