Utilities¶

chickadee.py¶

A command-line application to provide context for an IP address.

This utility leveraged libchickadee to extract, resolve, and report IP addresses. Please see Installation instructions for details on setting up this tool on your system.

Usage¶

usage: chickadee [-h] [-r {ip_api,virustotal}] [-f FIELDS]
                 [-t {json,jsonl,csv}] [-w FILENAME.JSON] [-n] [--no-count]
                 [-s] [--lang {en,de,es,pt-BR,fr,ja,zh-CN,ru}] [-b]
                 [-c CONFIG] [-p] [-v] [-V] [-l LOG]
                 [data [data ...]]

Yet another GeoIP resolution tool.

Will default to the free rate limited ip-api.com service for resolution.
You can specify the paid API key for ip-api.com or for VirusTotal in
the Chickadee configuration file. Please see template_chickadee.ini
for more information.

positional arguments:
  data                  Either an IP address, comma delimited list of IP addresses,
                        or path to a file or folder containing files to check for IP
                        address values. Currently supported file types: plain text
                        (ie logs, csv, json), gzipped plain text, xlsx
                        (must be xlsx extension). Can accept plain text data as
                        standard input.
                        (default: stdin)

optional arguments:
  -h, --help            show this help message and exit
  -r {ip_api,virustotal}, --resolver {ip_api,virustotal}
                        Resolving service to use. Must specify api key in config file.
                        Please see template_chickadee.ini for instructions.
                        (default: ip_api)
  -f FIELDS, --fields FIELDS
                        Comma separated fields to query (default: None)
  -t {json,jsonl,csv}, --output-format {json,jsonl,csv}
                        Output format (default: jsonl)
  -w FILENAME.JSON, --output-file FILENAME.JSON
                        Path to file to write output
                        (default: stdout)
  -n, --no-resolve      Only extract IP addresses, don't resolve. (default: False)
  --no-count            Disable counting the occurrences of IP addresses extracted
                        from source files (default: False)
  -s, --single          Use the significantly slower single item API. Adds reverse
                        DNS. (default: False)
  --lang {en,de,es,pt-BR,fr,ja,zh-CN,ru}
                        Language (default: en)
  -b, --include-bogon   Include BOGON addresses in results. (default: False)
  -c CONFIG, --config CONFIG
                        Path to config file to load (default: None)
  -p, --progress        Enable progress bar (default: False)
  -v, --verbose         Include debug log messages (default: False)
  -V, --version         Displays version
  -l LOG, --log LOG     Path to log file (default: chickadee.log)

Built by Chapin Bryce, v.20200805.0

chickadee Examples¶

Input options¶

Parsing a single IP address:

chickadee 1.1.1.1

Parsing multiple IP addresses:

chickadee 1.1.1.1,2.2.2.2

Parsing IPs from STDIN:

cat file.txt | chickadee

Parsing IPs from a file:

chickadee file.txt

Parsing IPs from a folder, recursively:

chickadee folder/

Resolver options¶

Resolve using VirusTotal (set API key in config file):

chickadee -r virustotal 1.1.1.1

Resolve using ip-api (set API key in config file):

chickadee -r ip_api 1.1.1.1

Output options¶

Reporting to JSON format:

chickadee 1.1.1.1 -t json

Reporting to JSON lines format:

chickadee 1.1.1.1 -t jsonl

Reporting to CSV format:

chickadee 1.1.1.1 -t csv

Other Arguments¶

Changing the fields to resolve and report on (ip_api):

chickadee -r ip_api -f query,count,asn,isp,org 1.1.1.1

Changing the fields to resolve and report on (virustotal):

chickadee -r virustotal -f query,detected_samples 1.1.1.1

Changing the output location (STDOUT by default)

chickadee 1.1.1.1 -w resolve.json

Only extract IP addresses, don’t resolve:

chickadee -n 1.1.1.1

Module Documentation¶

class libchickadee.chickadee.Chickadee(out_format='json', outfile=<colorama.ansitowin32.StreamWrapper object>, fields=None)¶

Class to handle chickadee script operations.

Parameters

out_format (str) – One of json, jsonl, csv
outfile (str or file_obj) – Destination to write report.
fields (list) – Collection of fields to resolve and report on.

Returns

None

Examples

>>> chickadee = Chickadee()
>>> resolution = chickadee.run('1.1.1.1')
>>> print(resolution)

dir_handler(folder_path)¶

Handle parsing IP addresses from files recursively.

Passes discovered files to the self.file_handler method for further processing.

Parameters: folder_path (str) – Directory path to recursively search for files.
Returns: dictionary of distinct IP addresses to resolve.
Return type: data_dict (dict)

static file_handler(file_path, ignore_bogon)¶

Handle parsing IP addresses from a file.

Will evaluate format of input file or file stream. Currently supports plain text, gzipped compressed plain text, and xlsx.

Parameters

file_path (str or file_obj) – Path of file to read or stream.
ignore_bogon (bool) – Whether to include BOGON addresses in results.

Returns

dictionary of distinct IP addresses to resolve.

Return type

data_dict (dict)

static get_api_key()¶

DEPRECIATED

Retrieve an API key set as an environment variable. Looks for value in CHICKADEE_API_KEY. May be depreciated in the near future.

Returns: API key, if found
Return type: (str)

get_resolver(api_key)¶

Determine the proper resolver to use, based on the available API keys.

Parameters: api_key (str) – API key value to register with the resolver
Returns: Instance of an initialized resolver

resolve(data_dict, api_key=None)¶

Resolve IP addresses stored as keys within data_dict. The values for each key should represent the number of occurrences of an IP within a data set.

Parameters

data_dict (dict) – Structured as {IP: COUNT}
api_key (str) – API Key for IP resolver.

Returns

List containing resolved IP address information

Return type

results (list)

run(input_data, api_key=None)¶

Evaluate the input data format to extract and resolve IP addresses.

Will check the self.input_data type and select the proper handler. This includes handling files, directories, STDIN, and python strings and sending to the proper handler to extract IPs

Once extracted, the IP addresses are passed to the self.resolve() method if the self.resolve_ips option is enabled.

Parameters

input_data (str or file_obj) – User provided data containing IPs to resolve
api_key (str) – API Key for IP resolver.

Returns

List of dictionaries containing resolved hits.

Return type

(list)

static str_handler(data)¶

Handle string input of one or more IP addresses and returns the distinct IPs with their associated frequency count.

Parameters: data (list, str) – raw input data from user
Returns: dictionary of distinct IP addresses to resolve.
Return type: data_dict (dict)

write_output(results)¶

Write results to output format and/or files.

Leverages the writers found in libchickadee.resolvers. Currently supports csv, json, and json lines formats, specified in self.out_format.

Parameters: results (list) – List of GeoIP results
Returns: None

class libchickadee.chickadee.CustomArgFormatter(prog, indent_increment=2, max_help_position=24, width=None)¶: Custom argparse formatter class

libchickadee.chickadee.arg_handling(args)¶

Parses command line arguments.

Returns: argparse Namespace containing argument parameters.

libchickadee.chickadee.config_handing(config_file=None, search_conf_path=None)¶

Parse config file and return argument values.

Parameters

config_file (str) – Path to config file to read values from.
search_conf_path (list) – List of paths to look for config file

Returns

dictionary containing configuration options.

libchickadee.chickadee.entry(args=None)¶

Entrypoint for package script.

Parameters: args – Arguments from invocation.

libchickadee.chickadee.find_config_file(search_conf_path=None, filename_patterns=None)¶

Handles the search operations for identifying configuration files on the system

Parameters

search_conf_path (str) – Path to look for a configuration file
filename_patterns (list) – Patterns to use to find a configuration file

Returns

The path to the first identified configuration file.

Return type

(str)

libchickadee.chickadee.join_config_args(config, args, definitions=None)¶

Join config file and argument parameters, where the args override configs.

Parameters

config (dict) – Dictionary containing parameters from config file.
args (obj) – Argparse namespace containing command line parameters.
definitions (dict) – Dictionary of parameters to check for in args and config.

Returns

Parameter information to use for script execution.

Return type

(dict)

libchickadee.chickadee.parse_config_sections(conf, section_defs)¶

Parse the sections of the configuration file

Parameters

conf (dict) – Loaded configuration file information
section_defs (dict) – Mapping of configuration file values and defaults

Returns

Final configuration to use with the script execution

Return type

(dict)

libchickadee.chickadee.setup_logging(path, verbose=False)¶

Function to setup logging configuration

Parameters

path (str) – File path to write log messages to
verbose (bool) – If the debug messages should be displayed on STDERR

Returns

None

Utilities¶

chickadee.py¶

Usage¶

chickadee Examples¶

Input options¶

Resolver options¶

Output options¶

Other Arguments¶

Module Documentation¶

Indices and tables¶

Table of Contents

Previous topic

Next topic

This Page