view release on metacpan or  search on metacpan

lib/ACL/Regex.pm  view on Meta::CPAN

    			push ( @{ $self->{ACL} }, $sanitized );
    		}
	} ## end while ( <FD> )
	close( FD );
	return( $self );
} ## end sub parse_acl_from_file( $$ )

sub match ($$) {
	my ( $self, $action ) = @_;

	my ($rc,$rs,$sanitized) = $self->sanitize_action( $action );

	return( $rc,$rs,'')
		if $rc < 0;

	for my $regex ( @{ $self->{ACL} } ) {
		return ( 1, $regex, $self->{message}->{"$regex"} ) if ( $sanitized =~ /$regex/i );
	}

	return ( 0, '', '' );
} ## end sub match ($$)

1;
# vim: set ai ts=4 nu:

__END__

=head1 NAME

ACL::Regex - Process arbitrary events with regular expressions.

=head1 SYNOPSIS

   use ACL::Regex;

   # Instantiate a reject object
   my $reject_acl = ACL::Regex->new->
           generate_required( 'required.txt' )->
           parse_acl_from_file( { Filename => "acl.reject.txt" } );

   while( <> ){
           chomp;
           my ($rc,$regex,$comment) = $reject_acl->match( $_ );
           if( $rc ){
                  print "\t! Rejected against $regex\n";
                  print "\t: Reason: $comment\n";
                  next;
           }
   }

=head1 DESCRIPTION

ACL::Regex allows you to parse a series of actions, key/value pairs through
an object containing a series of regular expressions.

=head2 OBJECT ORIENTED INTERFACE

The module is written with an object oriented interface.  There is no function
interface to choose from.  To streamline many of the initial operations of the
object, many of the initialization methods return the object reference, allowing
the programmer to chain the commands together.

=over 4

=item B<generate_required>

This method pulls in a I<:file> containing a series of required keys.

=item B<sanitize_acl>

This method re-sorts the keys in alphabetical order.

=item B<sanitize_action>

This method accomplishes the same thing as B<:sanitize_acl>
but for actions.

=item B<parse_acl_from_file>

This method takes a hash as a parameter:

  parse_acl_from_file( { Filename => "acl.reject.txt" } )

=item B<match>

This method takes an action as a parameter, and returns a triplet
containing the return code, matched regex, and any comment associated
with the regex.

=back

=head2 INPUT FILES

=head3 ACL REGEX FILE

An example of ain input ACL file can be found in the I<t> folder of this project, but it simply
comprises of rows that look like:

  # Don't allow domain admins to delete mailboxes on weekends or mondays
  /action=[mac-delete-mailbox] account=[.*@domain.net.adm] group=[domain-admin] dow=[sat|sun|mon]/        Domain admins can only delete mailboxes during the week
  # Reject mail from brazil
  /account=[.*@example.net] ip=[200..*] group=[user] action=[send-mail]/  No mail to be sent from Brazil!

The two tab deliminated columns separate the regex acl and the comment returned if any
match is found.

=head3 REQUIRED FILE

The required file is supplied to the object during instantiation and will seed
the object with a list of I<required> keys in the hash.  This way, if a key regex
isn't present in the B<ACL REGEX FILE> then the object will fill the hash with
a regex that I<matches all> possibilities.  This is designed to satisfy the regex
string should a key be absent from the action line.

  # This file contains a list of actions, and required attributes
  send-mail=account,ip,group,dow,time
  rwi_login=account,ip,auth_method,dow,time
  create_user=account,ip

=head3 ACTION FILE