NAME

CAPE::Utils - A helpful library for with CAPE.

VERSION

Version 1.0.1

SYNOPSIS

Quick summary of what the module does.

Perhaps a little code snippet.

use CAPE::Utils;

my $cape_util=CAPE::Utils->new();

my $sub_results=$cape_util->submit(items=>@to_detonate,unique=>0, quiet=>1);
use JSON;
print encode_json($sub_results)."\n";

METHODS

new

Initiates the object. One argument is taken and that is the path to the INI config file. The default is '/usr/local/etc/cape_utils.ini' and if not found, the defaults will be used.

my $cape_util=CAPE::Utils->new('/path/to/some/config.ini');

connect

Return a DBH from DBI->connect for the CAPE SQL server.

This will die with the output from $DBI::errstr if it fails.

my $dbh = $cape->connect;

fail

Set one or more pending tasks to failed as below.

UPDATE tasks SET status = 'failed_processing' WHERE status = 'pending'

The following options are also supported.

- where :: Additional SQL where statements to add. Something must
           be specified for this, unless fail_all in the config is
           true. Otherwise this method will die.

my $rows=$cape_util->fail( where=>"target like '%foo%'");

get_pending_count

Get pending count pending tasks.

- where :: And additional where part of the SQL statement. "and" will
           automatically be used to join it with the rest of the
           statement. May not contain a ';'.
    - Default :: undef

my $count=$cape_util->get_pending_count;

get_pending

Returns a arrah ref of hash refs of rows from the tasks table where the status is set to pending via "select * from tasks where status = 'pending'"

- where :: And additional where part of the SQL statement. "and" will
           automatically be used to join it with the rest of the
           statement. May not contain a ';'.
    - Default :: undef

- where :: Additional SQL where statements to add.

get_pending_table

Generates a ASCII table for pending.

The following config variables can are relevant to this and may be overriden.

table_border
table_color
pending_columns
pending_target_clip
pending_time_clip

The following options are also supported.

- where :: And additional where part of the SQL statement. "and" will
           automatically be used to join it with the rest of the
           statement. May not contain a ';'.
    - Default :: undef

print $cape_util->get_pending_table( pending_columns=>'id,package');

get_running

Returns a array ref of hash refs of rows from the tasks table where the status is set to pending.

select * from tasks where status = 'running'

The statement above is used to find running tasks.

- where :: And additional where part of the SQL statement. "and" will
           automatically be used to join it with the rest of the
           statement. May not contain a ';'.
    - Default :: undef

use Data::Dumper;

my $running=$cape_utils->get_running;
print Dumper($running);

get_running_count

Get pending count running tasks.

select * from tasks where status = 'running'

The statement above is used to find running tasks.

- where :: And additional where part of the SQL statement. "and" will
           automatically be used to join it with the rest of the
           statement. May not contain a ';'.
    - Default :: undef

my $count=$cape_util->get_running_count;

get_running_table

Generates a ASCII table for pending.

The following config variables can are relevant to this and may be overriden.

table_border
table_color
running_columns
running_target_clip
running_time_clip

The statement below is used to find running tasks.

select * from tasks where status = 'running'

The following options are also supported.

- where :: And additional where part of the SQL statement. "and" will
           automatically be used to join it with the rest of the
           statement. May not contain a ';'.
    - Default :: undef

print $cape_util->get_pending_table( pending_columns=>'id,package');

get_tasks

Returns a array ref of hash refs of rows from the tasks table where the status is set to pending.

- where :: The where part of the SQL statement. May not contain a ';'.
    - Default :: undef

- order :: Column to order by.
    - Default :: id

- limit :: Number of items to return.
    - Default :: 100

- direction :: Direction to order in.
    - Default :: desc

use Data::Dumper;

A small example showing getting running, ordering by category, and limiting to 20.

my $tasks=$cape_utils->get_tasks(where=>"status = 'running'", limit=>20, order=>"category", direction=>'desc');
print Dumper($running);

get_tasks_count

Gets a count of tasks.

- where :: The where part of the SQL statement. May not contain a ';'.
    - Default :: undef

use Data::Dumper;

A small example showing getting running, ordering by category, and limiting to 20.

my $count=$cape_util->get_tasks_count(where=>"status = 'running'", limit=>20, order=>"category", direction=>'desc');

get_tasks_table

Generates a ASCII table for tasks.

The following config variables can are relevant to this and may be overriden.

table_border
table_color
task_columns
task_target_clip
task_time_clip

The following options are also supported.

- where :: Additional SQL where statements to add.
    - Default :: undef

- order :: Column to order by.
    - Default :: id

- limit :: Number of items to return.
    - Default :: 100

- direction :: Direction to order in.
    - Default :: desc

print $cape_util->get_tasks_table( where => "status = 'reported'");

search

Searches the list of tasks. By default everything will be return ed.

- where :: Additional SQL where statements to use for searching.
           May not contain a ';'.
  - Default :: undef

Addtionally there are also helpers for searching. These may not contain either a /\'/ or a /\\/. They will be joined via and.

The following are handled as a simple equality.

- timeout
- memory
- enforce_timeout
- timedout

The following are numeric. Each one may accept multiple comma sperated values. The equalities =, >,>=, <=, and ! are supported. If no equality is specified, then = is used.

- id
- timeout
- priority
- dropped_files
- running_processes
- api_calls
- domains
- signatures_total
- signatures_alert
- files_written
- registry_keys_modified
- crash_issues
- anti_issues
- sample_id
- machine_id

# will result in id >= 3 and id < 44
id => '>=3,<44'

# either of these will be id = 4
id => '=4'
id => '4'

The following are string items. As is, they are evaluated as a simple equality. If ending with ending in '_like', they will be evaluated as a like.

- target
- category
- custom
- machine
- package
- route
- tags_tasks
- options
- platform

# becomes... target = 'foo'
target => 'foo'

# becomes... target like 'foo%'
target_like => 'foo%'

submit

Submits files to CAPE.

- clock :: Timestamp to use for setting the clock to of the VM for
  when executing the item. If left undefined, it will be
  autogenerated.
  - Format :: mm-dd-yyy HH:MM:ss

- items :: A array ref of items to submit. If a directory is listed in
  here, it will be read, but subdirectories will not be recursed. They
  will be ignored.

- name_regex :: Regex to use for matching items in a submitted dir.
  Only used if the a submitted item is a dir.
  - Default :: undef

- mime_regex :: Array ref of desired mime types to match via
  regex. Only used if the a submitted item is a dir.
  - Default :: undef

- timeout :: Value to use for timeout. Set to 0 to not enforce.
  - Default :: 200

- machine :: The machine to use for this. If not defined, first
  available will be used.
  - Default :: undef

- package :: Package to use, if not letting CAPE decide.
  - Default :: undef

- options :: Option string to be passed via --options.
  - Default :: undef

- random :: If it should randomize the order of submission.
  - Default :: 1

- tags :: Tags to be passed to the script via --tags.
  - Default :: undef

- platform :: What to pass to --platform.
  - Default :: undef

- custom :: Any custom values to pass via --custom.
  - Default :: undef

- enforce_timeout :: Force it to run the entire period.
  - Default :: 0

- unique :: Only submit it if it is unique.
    - Default :: 0

-quiet :: Do not print the results.
    - Default :: 0

The retuned value is a hash ref where the keys are successfully submitted files and values of those keys is the task ID.

my $sub_results=$cape_util->submit(items=>@to_detonate,unique=>0, quiet=>1);
use JSON;
print encode_json($sub_results)."\n";

timestamp

Creates a timestamp to be used with utils/submit. localtime is used to get the current time.

print $cape_util->timestamp."\n";

shuffle

Performa a Fisher Yates shuffle on the passed array ref.

check_remote

Checks the remote connection.

Two variablesare required, API key and IP.

$results=$cape_utils->check_remote(apikey=>$apikey, remote=>$remote_ip);
if (!$results){
    print "unauthed\n";
    return;
}

CONFIG FILE

The default config file is '/usr/local/etc/cape_utils.ini'.

The defaults are as below, which out of the box, it will work by default with CAPEv2 in it's default config.

# The DBI dsn to use
dsn=dbi:Pg:dbname=cape
# DB user
user=cape
# DB password
pass=
# the install base for CAPEv2
base=/opt/CAPEv2/
# 0/1 if poetry should be used
poetry=1
# 0/1 if fail should be allowed to run with out a where statement
fail_all=0
# colums to use for pending table show
pending_columns=id,target,package,timeout,ET,route,options,clock,added_on
# colums to use for runniong table show
running_columns=id,target,package,timeout,ET,route,options,clock,added_on,started_on,machine
# colums to use for tasks table
task_columns=id,target,package,timeout,ET,route,options,clock,added_on,latest,machine,status
# if the target column for running table display should be clipped to the filename
running_target_clip=1
# if microseconds should be clipped from time for running table display
running_time_clip=1
# if the target column for pending table display should be clipped to the filename
pending_target_clip=1
# if microseconds should be clipped from time for pending table display
pending_time_clip=1
# if the target column for task table display should be clipped to the filename
task_target_clip=1
# if microseconds should be clipped from time for task table display
task_time_clip=1
# default table color
table_color=Text::ANSITable::Standard::NoGradation
# default table border
table_border=ASCII::None
# when submitting use now for the current time
set_clock_to_now=1
# default timeout value for submit
timeout=200
# default value for enforce timeout for submit
enforce_timeout=0
# how to auth for mojo_cape_submit
# ip = match against subnets
# apikey = use apikey
# both = require both to match
# either = either may work
auth=ip
# the api key to for with mojo_cape_submit
#apikey=
# comma seperated list of allowed subnets for mojo_cape_submit
subnets=192.168.0.0/16,127.0.0.1/8,::1/128,172.16.0.0/12,10.0.0.0/8
# incoming dir to use for mojo_cape_submit
incoming=/malware/client-incoming
# directory to store json data files for submissions recieved by mojo_cape_submit
incoming_json=/malware/incoming-json

AUTHOR

Zane C. Bowers-Hadley, <vvelox at vvelox.net>

BUGS

Please report any bugs or feature requests to bug-cape-utils at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=CAPE-Utils. 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 CAPE::Utils

You can also look for information at:

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

https://rt.cpan.org/NoAuth/Bugs.html?Dist=CAPE-Utils
CPAN Ratings

https://cpanratings.perl.org/d/CAPE-Utils
Search CPAN

https://metacpan.org/release/CAPE-Utils

"CAPE-Utils.git" in git@github.com:VVelox
Web

https://github.com/VVelox/CAPE-Utils

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)

1 POD Error

The following errors were encountered while parsing the POD:

Around line 1406:: Unknown directive: =head

To install CAPE::Utils, copy and paste the appropriate command in to your terminal.

cpanm

cpanm CAPE::Utils

CPAN shell

perl -MCPAN -e shell
install CAPE::Utils

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

VERSION

SYNOPSIS

METHODS

new

connect

fail

get_pending_count

get_pending

get_pending_table

get_running

get_running_count

get_running_table

get_tasks

get_tasks_count

get_tasks_table

search

submit

timestamp

shuffle

check_remote

CONFIG FILE

AUTHOR

BUGS

SUPPORT

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Module Install Instructions