request-tracker3.8 3.8.11-1 / usr / bin / rt-crontool-3.8

#!/usr/bin/perl
# BEGIN BPS TAGGED BLOCK {{{
#
# COPYRIGHT:
#
# This software is Copyright (c) 1996-2011 Best Practical Solutions, LLC
#                                          <sales@bestpractical.com>
#
# (Except where explicitly superseded by other copyright notices)
#
#
# LICENSE:
#
# This work is made available to you under the terms of Version 2 of
# the GNU General Public License. A copy of that license should have
# been provided with this software, but in any event can be snarfed
# from www.gnu.org.
#
# This work is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
# General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
# 02110-1301 or visit their web page on the internet at
# http://www.gnu.org/licenses/old-licenses/gpl-2.0.html.
#
#
# CONTRIBUTION SUBMISSION POLICY:
#
# (The following paragraph is not intended to limit the rights granted
# to you to modify and distribute this software under the terms of
# the GNU General Public License and is only of importance to you if
# you choose to contribute your changes and enhancements to the
# community by submitting them to Best Practical Solutions, LLC.)
#
# By intentionally submitting any modifications, corrections or
# derivatives to this work, or any other work intended for use with
# Request Tracker, to Best Practical Solutions, LLC, you confirm that
# you are the copyright holder for those contributions and you grant
# Best Practical Solutions,  LLC a nonexclusive, worldwide, irrevocable,
# royalty-free, perpetual, license to use, copy, create derivative
# works based on those contributions, and sublicense and distribute
# those contributions and any derivatives thereof.
#
# END BPS TAGGED BLOCK }}}
 
=head1 NAME

rt-crontool - Command-line interface to Request Tracker

=head1 SYNOPSIS

 rt-crontool [--verbose] --search <module> --search-arg <argument> \
     --condition <module> --condition-arg <argument> \
     --action <module> --action-arg <argument>

=head1 EXAMPLES

 rt-crontool --search RT::Search::ActiveTicketsInQueue \
     --search-arg General \
     --condition RT::Condition::UntouchedInHours \
     --condition-arg 4 \
     --action RT::Action::SetPriority \
     --action-arg \
     --verbose

=head1 SECURITY

This tool allows the user to run arbitrary perl modules from within RT.

If this tool were setgid, a hostile local user could use this tool to
gain administrative access to RT.

It is suggested that you create a non-privileged Unix user with the
correct group membership and RT access to run this tool.

It is incredibly important that non-privileged users not be allowed to
run this tool.

=head1 INTERNALS

=cut

use strict;
use Carp;

# fix lib paths, some may be relative
BEGIN {
    require File::Spec;
    my @libs = ("/usr/share/request-tracker3.8/lib", "/usr/local/share/request-tracker3.8/lib");
    my $bin_path;

    for my $lib (@libs) {
        unless ( File::Spec->file_name_is_absolute($lib) ) {
            unless ($bin_path) {
                if ( File::Spec->file_name_is_absolute(__FILE__) ) {
                    $bin_path = ( File::Spec->splitpath(__FILE__) )[1];
                }
                else {
                    require FindBin;
                    no warnings "once";
                    $bin_path = $FindBin::Bin;
                }
            }
            $lib = File::Spec->catfile( $bin_path, File::Spec->updir, $lib );
        }
        unshift @INC, $lib;
    }

}

use RT;

use Getopt::Long;

use RT::Interface::CLI qw(CleanEnv GetCurrentUser GetMessageContent loc);

#Clean out all the nasties from the environment
CleanEnv();

my ( $search, $condition, $action, $search_arg, $condition_arg, $action_arg,
     $template, $template_id, $transaction, $transaction_type, $help, $log, $verbose );
GetOptions(
    "search=s"           => \$search,
    "search-arg=s"       => \$search_arg,
    "condition=s"        => \$condition,
    "condition-arg=s"    => \$condition_arg,
    "action-arg=s"       => \$action_arg,
    "action=s"           => \$action,
    "template=s"         => \$template,
    "template-id=s"      => \$template_id,
    "transaction=s"      => \$transaction,
    "transaction-type=s" => \$transaction_type,
    "log=s"              => \$log,
    "verbose|v"          => \$verbose,
    "help"               => \$help,
);

# Load the config file
RT::LoadConfig();

# adjust logging to the screen according to options
RT->Config->Set( LogToScreen => $log ) if $log;

#Connect to the database and get RT::SystemUser and RT::Nobody loaded
RT::Init();

require RT::Tickets;
require RT::Template;

#Get the current user all loaded
my $CurrentUser = GetCurrentUser();

# show help even if there is no current user
help() if $help;

unless ( $CurrentUser->Id ) {
    print loc("No RT user found. Please consult your RT administrator.\n");
    exit(1);
}

help() unless $search && $action;

$transaction = lc( $transaction||'' );
if ( $transaction && $transaction !~ /^(first|all|last)$/i ) {
    print STDERR loc("--transaction argument could be only 'first', 'last' or 'all'");
    exit 1;
}

if ( $template && $template_id ) {
    print STDERR loc("--template-id is deprecated argument and can not be used with --template");
    exit 1;
}
elsif ( $template_id ) {
# don't warn
    $template = $template_id;
}

# We _must_ have a search object
load_module($search);
load_module($action)    if ($action);
load_module($condition) if ($condition);

my $void_scrip = RT::Scrip->new( $CurrentUser );
my $void_scrip_action = RT::ScripAction->new( $CurrentUser );

#At the appointed time:

#find a bunch of tickets
my $tickets = RT::Tickets->new($CurrentUser);
my $search  = $search->new(
    TicketsObj  => $tickets,
    Argument    => $search_arg,
    CurrentUser => $CurrentUser
);

$search->Prepare();

# TicketsFound is an RT::Tickets object
my $tickets = $search->TicketsObj;

#for each ticket we've found
while ( my $ticket = $tickets->Next() ) {
    print $ticket->Id() . ": " if ($verbose);

    my $template_obj = get_template( $ticket );

    if ( $transaction ) {
        my $txns = get_transactions($ticket);
        my $found = 0;
        while ( my $txn = $txns->Next ) {
            print loc("Using transaction #[_1]...", $txn->id)
                if $verbose;
            process($ticket, $txn, $template_obj);
            $found = 1;
        }
        print loc("Couldn't find suitable transaction, skipping")
            if $verbose && !$found;
    } else {
        print loc("Processing without transaction, some conditions and actions may fail. Consider using --transaction argument")
            if $verbose;

        process($ticket, undef, $template_obj);
    }
}

sub process {
    my $ticket = shift;
    my $transaction = shift;
    my $template_obj = shift;

    # perform some more advanced check
    if ($condition) {
        my $condition_obj = $condition->new(
            TransactionObj => $transaction,
            TicketObj      => $ticket,
            ScripObj       => $void_scrip,
            TemplateObj    => $template_obj,
            Argument       => $condition_arg,
            CurrentUser    => $CurrentUser,
        );

        # if the condition doesn't apply, get out of here

        return unless $condition_obj->IsApplicable;
        print loc("Condition matches...") if $verbose;
    }

    #prepare our action
    my $action_obj = $action->new(
        TicketObj      => $ticket,
        TransactionObj => $transaction,
        TemplateObj    => $template_obj,
        Argument       => $action_arg,
        ScripObj       => $void_scrip,
        ScripActionObj => $void_scrip_action,
        CurrentUser    => $CurrentUser,
    );

    #if our preparation, move onto the next ticket
    return unless $action_obj->Prepare;
    print loc("Action prepared...") if $verbose;

    #commit our action.
    return unless $action_obj->Commit;
    print loc("Action committed.\n") if $verbose;
}

=head2 get_transactions

Takes ticket and returns L<RT::Transactions> object with transactions
of the ticket according to command line arguments C<--transaction>
and <--transaction-type>.

=cut

sub get_transactions {
    my $ticket = shift;
    my $txns = $ticket->Transactions;
    my $order = $transaction eq 'last'? 'DESC': 'ASC';
    $txns->OrderByCols(
        { FIELD => 'Created', ORDER => $order },
        { FIELD => 'id', ORDER => $order },
    );
    if ( $transaction_type ) {
        $transaction_type =~ s/^\s+//;
        $transaction_type =~ s/\s+$//;
        foreach my $type ( split /\s*,\s*/, $transaction_type ) {
            $txns->Limit( FIELD => 'Type', VALUE => $type, ENTRYAGGREGATOR => 'OR' );
        }
    }
    $txns->RowsPerPage(1) unless $transaction eq 'all';
    return $txns;
}

=head2 get_template

Takes a ticket and returns a template according to command line options.

=cut

{ my $cache = undef;
sub get_template {
    my $ticket = shift;
    return undef unless $template;

    unless ( $template =~ /\D/ ) {
        # by id
        return $cache if $cache;

        my $cache = RT::Template->new( $RT::SystemUser );
        $cache->Load( $template );
        die "Failed to load template '$template'"
            unless $cache->id;
        return $cache;
    }

    my $queue = $ticket->Queue;
    return $cache->{ $queue } if $cache->{ $queue };

    my $res = RT::Template->new( $RT::SystemUser );
    $res->LoadQueueTemplate( Queue => $queue, Name => $template );
    unless ( $res->id ) {
        $res->LoadGlobalTemplate( $template );
        die "Failed to load template '$template', either for queue #$queue or global"
            unless $res->id;
    }
    return $cache->{ $queue } = $res;
} }

# {{{ load_module 

=head2 load_module

Loads a perl module, dying nicely if it can't find it.

=cut

sub load_module {
    my $modname = shift;
    eval "require $modname";
    if ($@) {
        die loc( "Failed to load module [_1]. ([_2])", $modname, $@ );
    }

}

# }}}

# {{{ loc 

=head2 loc LIST

Localize this string, with the current user's currentuser object

=cut

sub loc {
    $CurrentUser->loc(@_);
}

# }}}

sub help {

    print loc( "[_1] is a tool to act on tickets from an external scheduling tool, such as cron.", $0 )
      . "\n";
    print loc("It takes several arguments:") . "\n\n";

    print "	"
      . loc( "[_1] - Specify the search module you want to use", "--search" )
      . "\n";
    print "	"
      . loc( "[_1] - An argument to pass to [_2]", "--search-arg", "--search" )
      . "\n";

    print "	"
      . loc( "[_1] - Specify the condition module you want to use", "--condition" )
      . "\n";
    print "	"
      . loc( "[_1] - An argument to pass to [_2]", "--condition-arg", "--condition" )
      . "\n";
    print "	"
      . loc( "[_1] - Specify the action module you want to use", "--action" )
      . "\n";
    print "	"
      . loc( "[_1] - An argument to pass to [_2]", "--action-arg", "--action" )
      . "\n";
    print "	"
      . loc( "[_1] - Specify name or id of template(s) you want to use", "--template" )
      . "\n";
    print "	"
      . loc( "[_1] - Specify if you want to use either 'first', 'last' or 'all' transactions", "--transaction" )
      . "\n";
    print "	"
      . loc( "[_1] - Specify the comma separated list of transactions' types you want to use", "--transaction-type" )
      . "\n";
    print "	"
      . loc( "[_1] - Adjust LogToScreen config option", "--log" ) . "\n";
    print "	"
      . loc( "[_1] - Output status updates to STDOUT", "--verbose" ) . "\n";
    print "\n";
    print "\n";
    print loc("Security:")."\n";
    print loc("This tool allows the user to run arbitrary perl modules from within RT.")." ". 
        loc("If this tool were setgid, a hostile local user could use this tool to gain administrative access to RT.")." ".
        loc("It is incredibly important that nonprivileged users not be allowed to run this tool."). " " . 
        loc("It is suggested that you create a non-privileged unix user with the correct group membership and RT access to run this tool.")."\n";
    print "\n";
    print loc("Example:");
    print "\n";
    print " "
      . loc( "The following command will find all active tickets in the queue 'general' and set their priority to 99 if they are overdue:"
      )
      . "\n\n";

    print " bin/rt-crontool \\\n";
    print "  --search RT::Search::ActiveTicketsInQueue  --search-arg general \\\n";
    print "  --condition RT::Condition::Overdue \\\n";
    print "  --action RT::Action::SetPriority --action-arg 99 \\\n";
    print "  --verbose\n";

    print "\n";
    print loc("Escalate tickets"). "\n";
    print " bin/rt-crontool \\\n";
    print "  --search RT::Search::ActiveTicketsInQueue  --search-arg general \\\n";
    print "  --action RT::Action::EscalatePriority\n";
 
 
 



    exit(0);
}