ifxlookup/README

# ifxlookup
#### A python lookup module and command-line tool for infrastructure equipment.

IFXTool takes search terms (subjects) such as IP addresses, hostnames, mac addresses, and other identifiers and performs
queries against various infrastructure equipment to return datasets for those subjects. Information on some
subjects may be found across multiple services. For example, the Bluecat server and the Aruba controller may both have information on an IP address. Including -b and -w will retrieve information on the IP address from both
services.

IFXTool is extensible, so that anyone can write plugins for their specific service to be included in the lookup.
By default, several plugins are included.


## Installation

* Clone the repository
* `cd ifxlookup`
* ( optional )
`python3 -m venv ./ && bin/activate`
* `pip install -r requirements.txt`


## Command-Line Tool (ifxlookup.py)

### Usage

```
usage: ifxlookup.py [-h] [-c CONFIG] [-f FILTER] [-j] [-cg] [-b] [-gc] [-d]
                    [-r] [-w] [-s] [-fw] [-v] [-a]
                    subjects [subjects ...]

positional arguments:
  subjects              IP's, hostnames, MAC's, usernames, or other strings to
                        look up.

optional arguments:
  -h, --help            show this help message and exit
  -c CONFIG, --config CONFIG
                        Specify a config file (~/.config/ifxlookup.yml by
                        default)
  -f FILTER, --filter FILTER
                        Apply a JSONPath filter to the results
  -j, --json            Return results as a json object
  -cg, --vip            Return VIP information about the subject (f5)
  -b, --bluecat         Return network information about the subject (bluecat)
  -gc, --guid_channels  Return working channels for GUID (guid_channels)
  -d, --dns             Return DNS resolution about the subject (dns)
  -r, --vpn             Return VPN information about the subject (openvpn)
  -w, --wifi            Return wireless connection information about the
                        subject (aruba)
  -s, --shodan          Return Shodan information about the subject (dns)
  -v, --debug           Include debug information in the output. Add 'v's for
                        more output.
  -a, --all             Return all searchable information about the subject
```

## Module Documentation

### class IFXLookup

#### configure(config)
`ifxlookup.IFXLookup.configure(self,config)`

Updates the configuration of the lookup with the given config.

#### debug_level()
` ifxlookup.IFXLookup.debug_level(self)`

Gets the debug level.

#### disable_caching()
`ifxlookup.IFXLookup.disable_caching(self)`

Disables results caching and enables auto-shutdown of plugins.

#### dump_config()
`ifxlookup.IFXLookup.dump_config(self)`

Returns the current configuration state. This likely contains sensitive information such as API keys.


#### dump_config_to_file(path,print_json)
`ifxlookup.IFXLookup.dump_config_to_file(self,path,print_json=False)`

Exports the current plugin configuration to a file.

#### enable_caching()
`ifxlookup.IFXLookup.enable_caching(self)`

Enables results caching and disables auto-shutdown of plugins.

#### finish()
`ifxlookup.IFXLookup.finish(self)`

In the case that caching has been enabled, this enables the plugins to be manually shut down.

#### get_plugins()
`ifxlookup.IFXLookup.get_plugins(self)`

Returns a map of plugins configured to use in the lookup.

#### search_plugins(directory)
`ifxlookup.IFXLookup.search_plugins(self,directory=None)`

Searches a given directory for compatible plugins and returns a map of available plugin names and classes

#### set_debug_level(level)
`ifxlookup.IFXLookup.set_debug_level(self,level)`

Sets the debug level.

#### use_plugins(plugins,reload)
`ifxlookup.IFXLookup.use_plugins(self,plugins,reload=False)`

Defines plugins that should be used in a lookup, optionally forcing them to reload.

### Example Application
```python
# Perform a DNS lookup with the DNS plugin
from ifxlookup import IFXLookup
lookup = IFXLookup()
lookup.configure({'dns':{'resolver':'1.1.1.1'}})
lookup.use_plugins(['dns'])
lookup.lookup(['google.com'])
```
## Plugins

IFXLookup works by loading plugins in the form of ServiceDelegate objects. Plugins are executed in alphabetical
order. ServiceDelegate objects are subclasses of the ServiceBase class, which includes the basic framework
for loading your plugin into IFXLookup. The ServiceDelegate subclass is concise enough to make writing simple
plugins straightforward and open enough to allow for complex implementations.

### Writing a Plugin

#### Template

To write a new plugin, create a python file with the name of your plugin in the 'plugins' directory. If you don't need to use your plugin in the command-line tool, you can place it wherever you want and import it manually. The name of
the plugin will be the name that appears in the plugin's report to the user. You can populate the file with the
following template:

```python
from servicebase import ServiceBase

class ServiceDelegate(ServiceBase) :
	def get_arguments(cls) :
		"""Returns an array of information used to construct an argumentparser argument."""
		# [ <short flag>,<unix flag>,<arg type>,<description> ]
        return [ '-nm', '--name', 'store_true', "Return the name of the subject" ]

	def lookup(self,subject) :
		"""Given a subject, return a dictionary or array of information about the subject."""
		return: {'name' : subject ]

```

The function `get_arguments` is used by the command line tool to determine when the plugin should be run,
based on the arguments the user supplied. Plugins are loaded whenever the script is run.

The function `lookup` is called for every subject the user submits. The subjects are passed in as
raw strings.

Within the `lookup` function, you should perform any lookups on the host and return a dictionary or
array of information about the subject. To make sure that the results are serializable, be sure that
dictionaries and arrays are the only data structures in your results.

#### Loading Configuration

The configuration file for IFXLookup is loaded and parsed for all plugins. The config file may be a JSON or YAML file that is
parsed into a python dictionary and available to your plugin as `self.confg`. You can specify whatever
configuration options you desire under your plugin's name in the config file, but it is up to your plugin
to check for mandatory or missing configuration options. See some of the default plugins for examples.

#### Convenience Functions

Your plugin may need to do some setup before executing lookups, such as logging into an API service or
caching a dataset for use in lookups. The convenience functions `startup()` and `shutdown()` are called
on your plugin before and after lookups are called on your plugin. This allows you to do any setup your
plugin needs without overriding `__init__()`. It also allows you to perform any cleanup your plugin may
need, such as logging out any outstanding sessions.

The `self.debug()` allows your plugin to print verbose output to the console if requested by the user.
This output is printed to `stderr` and not added to your plugin's report.

Example:

`self.debug("This message will be printed to the console when the user passes a -vv argument",2)`

Your plugin can report errors and warnings by appending them to the list `self._error` and `self._warn`,
respectively. They will be appended to the report for your plugin (or removed from the report if the
user specifies).

### Contributing

If you have a plugin for a piece of equipment that could be useful to others on the team, I'd love to add it
to the project. Submit a pull request and let's get it added!

## Justification

While reviewing reports from various network services I'd often find myself cross-referencing several sites to
get the information I was lookup for on a particular IP, mac address or host. What's more, the information I
gathered from each site had to be formatted by hand if I wanted to build a report of a particular host at a
particular time. I wrote this tool to keep from opening a bunch of tabs and copy-pasting information from
each into a text file for storage.