NAME

Cisco::IronPort - Interface to Cisco IronPort Reporting API

SYNOPSIS

        use Cisco::IronPort;

        my $ironport = Cisco::IronPort->new(
                username => $username,
                password => $password,
                server   => $server
        );

        my %stats = $ironport->incoming_mail_summary_current_hour;

        print "Total Attempted Messages : $stats{total_attempted_messages}{count}\n";
        print "Clean Messages : $stats{clean_messages}{count} ($stats{clean_messages}{percent}%)\n";

        # prints...
        # Total Attempted Messages : 932784938
        # Clean Messages : (34%)

METHODS

new ( %ARGS )

        my $ironport = Cisco::IronPort->new(
                username => $username,
                password => $password,
                server   => $server
        );

Creates a Cisco::IronPort object. The constructor accepts a hash containing three mandatory and one optional parameter.

username: The username of a user authorised to access the reporting API.
password: The password of the username used to access the reporting API.
server: The target IronPort device hosting the reporting API. This value must be either a resolvable hostname or an IP address.
proto: This optional parameter may be used to specify the protocol (either http or https) which should be used when connecting to the reporting API. If unspecified this parameter defaults to https.

incoming_mail_summary_current_hour

        my %stats = $ironport->incoming_mail_summary_current_hour;
        print "Total Attempted Messages : $stats{total_attempted_messages}{count}\n";

Returns a nested hash containing incoming mail summary statistics for the current hourly period. The hash has the structure show below:

        $stats = {
          'statistic_name_1' => {
            'count'   => $count,
            'percent' => $percent
          },
          'statistic_name_2' => {
            'count'   => $count,
            'percent' => $percent
          },
          ...

          'statistic_name_n => {
            ...
          }

Valid statistic names are show below - these names are derived from those returned by the reporting API with all spaces converted to underscores and all characters lower-cased.

        stopped_by_reputation_filtering 
        stopped_as_invalid_recipients 
        stopped_by_content_filter 
        total_attempted_messages 
        total_threat_messages 
        clean_messages 
        virus_detected
        spam_detected

incoming_mail_summary_current_day

Returns a nested hash with the same structure and information as described above for the incoming_mail_summary_current_hour method, but for a time period covering the current day.

incoming_mail_summary_current_hour_raw

Returns a scalar containing the incoming mail summary statistics for the current hour period unformated and as retrieved directly from the reporting API.

This method may be useful if you wish to process the raw data from the API call directly.

incoming_mail_summary_current_day_raw

Returns a scalar containing the incoming mail summary statistics for the current day period unformated and as retrieved directly from the reporting API.

This method may be useful if you wish to process the raw data from the API call directly.

incoming_mail_details_current_hour

        # Print a list of sending domains which have sent more than 50 messages
        # of which over 50% were detected as spam.

        my %stats = $ironport->incoming_mail_details_current_hour;
        
        foreach my $domain (keys %stats) {
          if ( ( $stats{$domain}{total_attempted} > 50 ) and 
               ( int (($stats{$domain}{spam_detected}/$stats{$domain}{total_attempted})*100) > 50 ) {
            print "Domain $domain sent $stats{$domain}{total_attempted} messages, $stats{$domain}{spam_detected} were marked as spam.\n"
          }
        }

Returns a nested hash containing details of incoming mail statistics for the current hour period. The hash has the following structure:

        sending.domain1.com => {
          begin_date                            => a human-readable timestamp at the beginning of the measurement interval (YYYY-MM-DD HH:MM TZ),
          begin_timestamp                       => seconds since epoch at the beginning of the measurement interval (resolution of 100ms),
          clean                                 => total number of clean messages sent by this domain,
          connections_accepted                  => total number of connections accepted from this domain,
          end_date                              => a human-readable timestamp at the end of the measurement interval (YYYY-MM-DD HH:MM TZ),
          end_timestamp                         => seconds since epoch at the end of the measurement interval (resolution of 100ms),
          orig_value                            => the domain name originally establishing the connection prior to any relaying or masquerading,
          sender_domain                         => the sending domain,
          spam_detected                         => the number of messages marked as spam from this domain,
          stopped_as_invalid_recipients         => number of messages stopped from this domain due to invalid recipients,
          stopped_by_content_filter             => number of messages stopped from this domain due to content filtering,
          stopped_by_recipient_throttling       => number of messages stopped from this domain due to recipient throttling,
          stopped_by_reputation_filtering       => number of messages stopped from this domain due to reputation filtering,
          total_attempted                       => total number of messages sent from this domain,
          total_threat                          => total number of messages marked as threat messages from this domain,
          virus_detected                        => total number of messages marked as virus positive from this domain
        },
        sending.domain2.com => {
          ...
        },
        ...
        sending.domainN.com => {
          ...
        }

Where each domain having sent email in the current hour period is used as the value of a hash key in the returned hash having the subkeys listed above. For a busy device this hash may contain hundreds or thousands of domains so caution should be excercised in storing and parsing this structure.

incoming_mail_details_current_day

This method returns a nested hash as described in the incoming_mail_details_current_hour method above but for a period of the current day. Consequently the returned hash may contain a far larger number of entries.

incoming_mail_details_current_hour_raw

Returns a scalar containing the incoming mail details for the current hour period as retrieved directly from the reporting API. This method is useful is you wish to access and/or parse the results directly.

incoming_mail_details_current_day_raw

Returns a scalar containing the incoming mail details for the current day period as retrieved directly from the reporting API. This method is useful is you wish to access and/or parse the results directly.

top_users_by_clean_outgoing_messages_current_hour

        # Print a list of our top internal users and number of messages sent.
        
        my %top_users = $ironport->top_users_by_clean_outgoing_messages_current_hour;

        foreach my $user (sort keys %top_users) {
          print "$user - $top_users{clean_messages} messages\n";
        }

Returns a nested hash containing details of the top ten internal users by number of clean outgoing messages sent for the current hour period. The hash has the following structure:

        'user1@domain.com' => {
          begin_date            => a human-readable timestamp of the begining of the current hour period ('YYYY-MM-DD HH:MM TZ'),
          begin_timestamp       => a timestamp of the beginning of the current hour period in seconds since epoch,
          end_date              => a human-readable timestamp of the end of the current hour period ('YYYY-MM-DD HH:MM TZ'),
          end_timestamp         => a timestamp of the end of the current hour period in seconds since epoch,
          internal_user         => the email address of the user (this may also be 'unknown user' if the address cannot be determined),
          clean_messages        => the number of clean messages sent by this user for the current hour period
        },
        'user2@domain.com' => {
          ...
        },
        ...
        user10@domain.com' => {
          ...
        }

top_users_by_clean_outgoing_messages_current_day

Returns a nested hash containing details of the top ten internal users by number of clean outgoing messages sent for the current day period.

top_users_by_clean_outgoing_messages_current_hour_raw

Returns a scalar containing the details of the top ten internal users by number of clean outgoing messages sent for the current hour period as retrieved directly from the reporting API.

This method may be useful if you wish to process the raw data retrieved from the API yourself.

top_users_by_clean_outgoing_messages_current_day_raw

Returns a scalar containing the details of the top ten internal users by number of clean outgoing messages sent for the current day period as retrieved directly from the reporting API.

This method may be useful if you wish to process the raw data retrieved from the API yourself.

average_time_in_workqueue_current_hour

        my %stats = $ironport->average_time_in_workqueue_current_day;
        
        foreach my $i (sort keys %stats) {
                print "$stats{$i}{end_date} : $stats{$i}{time}\n"
        }
        
        # Prints the average time a message spent in the workqueue for the current hourly period
        # e.g.
        # 2012-08-07 03:34 GMT : 1.76650943396
        # 2012-08-07 03:39 GMT : 4.97411003236
        # 2012-08-07 03:44 GMT : 0.955434782609
        # 2012-08-07 03:49 GMT : 3.38574040219
        # 2012-08-07 03:54 GMT : 2.32837301587
        # ...

This method returns a nested hash containing statistics for the average time a message spent in the workqueue for the previous hourly period - the hash has the following structure:

        measurement_period_1_begin_timestamp => {
          begin_timestamp       => a timestamp marking the beginning of the measurement period in seconds since epoch,
          end_timestamp         => a timestamp marking the ending of the measurement period in seconds since epoch,
          begin_date            => a human-readable timestamp marking the beginning of the measurement period (YYYY-MM-DD HH:MM:SS TZ),
          end_date              => a human-readable timestamp marking the ending of the measurement period (YYYY-MM-DD HH:MM:SS TZ),
          time                  => the average time in seconds a message spent in the workqueue for the measurement period
        },
        measurement_period_2_begin_timestamp => {
          ...
        },
        ...
        measurement_period_n_begin_timestamp => {
          ...
        }

average_time_in_workqueue_current_day

Returns a nested hash containing statistics for the average time a message spent in the workqueue for the previous daily period - the hash has the same structure as detailed in the average_time_in_workqueue_current_hour above.

average_time_in_workqueue_current_hour_raw

Returns a scalar containing statistics for the average time a message spent in the workqueue for the previous hourly period as retrieved directly from the reporting API.

This method may be useful if you wish to process the raw data retrieved from the API yourself.

average_time_in_workqueue_current_day_raw

Returns a scalar containing statistics for the average time a message spent in the workqueue for the previous daily period as retrieved directly from the reporting API.

This method may be useful if you wish to process the raw data retrieved from the API yourself.

AUTHOR

Luke Poskitt, <ltp at cpan.org>

BUGS

Please report any bugs or feature requests to bug-cisco-ironport at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Cisco-IronPort. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Cisco::IronPort

You can also look for information at:

RT: CPAN's request tracker (report bugs here)

http://rt.cpan.org/NoAuth/Bugs.html?Dist=Cisco-IronPort
AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/Cisco-IronPort
CPAN Ratings

http://cpanratings.perl.org/d/Cisco-IronPort
Search CPAN

http://search.cpan.org/dist/Cisco-IronPort/

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

To install Cisco::IronPort, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Cisco::IronPort

CPAN shell

perl -MCPAN -e shell
install Cisco::IronPort

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

METHODS

new ( %ARGS )

incoming_mail_summary_current_hour

incoming_mail_summary_current_day

incoming_mail_summary_current_hour_raw

incoming_mail_summary_current_day_raw

incoming_mail_details_current_hour

incoming_mail_details_current_day

incoming_mail_details_current_hour_raw

incoming_mail_details_current_day_raw

top_users_by_clean_outgoing_messages_current_hour

top_users_by_clean_outgoing_messages_current_day

top_users_by_clean_outgoing_messages_current_hour_raw

top_users_by_clean_outgoing_messages_current_day_raw

average_time_in_workqueue_current_hour

average_time_in_workqueue_current_day

average_time_in_workqueue_current_hour_raw

average_time_in_workqueue_current_day_raw

AUTHOR

BUGS

SUPPORT

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Module Install Instructions