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

IFXLookup 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.

IFXLookup 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
* `pip3 install ./ifxlookup`
* `cp ifxlookup/config_sample.yml ~/.config/ifxlookup.yml`
* Fill out missing values in `~/.config/ifxlookup.yml`
* `ifxlookup -h`

----
## Command-Line Tool (ifxlookup)

### Usage

```
usage: ifxlookup [-h] [-c CONFIG] [-f FILTER] [-j] [-cg] [-b] [-l] [-gc] [-d] [-cms] [-vm] [-r] [-w] [-s] [-fw] [-m] [-v] 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            Format output as json
  -cg, --vip            Return VIP information about the subject (f5)
  -b, --bluecat         Return network information about the subject (bluecat)
  -l, --ldap            Return LDAP information about the subject (ldap)
  -gc, --guid_channels  Return working channels for GUID
  -d, --dns             Return DNS resolution about the subject (dns)
  -cms, --channel       Return CMS channel info about the subject (cms)
  -vm, --vm             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)
  -fw, --rules          Return Firewall addresses, groups, and rules relating to the subject
  -m, --mac             Return vendor OUI from a MAC address (mac)
  -v, --debug           Include debug information in the output. Add 'v's for more output.
```

#### Configuring

The configuration file for the command line tool is located at `~/.config/ifxlookup.yml` by default, though a custom path may be specified on the command line. This config file may be a JSON or YAML file with an entry for each plugin in the plugins directory. A sample configuration file is provided in the repository for convenience. The config file is loaded and parsed for configuration info for all plugins in the plugins folder. Each plugin requires specific configuration options to work properly, and some plugins have optional configuration options. Every plugin used by the command line tool must have a line in the configuration file, even if that configuration is `{}`. For example, the DNS plugin has an optional configuration option of 'resolver' that takes an array of IP addresses. While this option is not required, an entry for DNS in the configuration file _is_ required to use the plugin. Therefore, the configuration file might look something like this:

```yaml
dns:
  resolver:
    - 1.1.1.1
    - 8.8.8.8
```
If you wish to use a plugin that accepts no configuration, the entry would be simply:
```yaml
dns: {}
```
#### Sample Config

I've provided a template config file, `config_sample.yml` that includes many of the options from my own config file, and can be filled out with a few addresses and credentials to get up and going right away. Don't forget to name it `~/.config/ifxlookup.yml` to use the command line tool without specifying `-c`.

#### Using filters

IFXLookup may filter the results returned by any and all plugins by applying a [JSONPath](https://goessner.net/articles/JsonPath/) filter to the results. For example, to only return the MX records of a DNS lookup for all search terms, the command would be:
```sh
ifxlookup -d -f '*.dns.mx' sling.com dish.com
```

#### Examples

To find the DHCP assigned gateway for a the IP 10.124.24.130:
```sh
ifxlookup -b 10.124.24.130 -f '*.bluecat.[*].parent.gateway'
```

To find the timestamps of the latest Shodan scans for the IP 67.21.62.46:
```sh
ifxlookup --shodan 67.21.62.46 -f '*.shodan.data[*].timestamp'
```

To find the MAC address of the wireless client connected with an IP of 10.124.24.131:
```sh
ifxlookup -w 10.124.24.131 -f '*.*.sta_mac_address'
```

To find what IP addresses are part of the VIP pool for the IP 74.206.195.149:
```sh
ifxlookup -cg 74.206.195.149 -f '*.*.members[*].address' -v
```

To find the manufacturing company of an ethernet device with the MAC address 38:F9:D3:A6:88:C7:
```sh
ifxlookup -m "38:F9:D3:A6:88:C7" -f "*.mac.company"
```

To find the email addresses of all LDAP users whose username starts with 'daniel':
```sh
ifxlookup -l daniel -f '*.ldap.*.mail[0]'
```
----
## Library Documentation

### class IFXLookup

#### configure(config)
```python
ifxlookup.IFXLookup.configure(self,config)
```
Updates the configuration of the lookup with the given config.

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

Gets the debug level.

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

Disables results caching and enables auto-shutdown of plugins.

#### dump_config()
```python
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)
```python
ifxlookup.IFXLookup.dump_config_to_file(self,path,print_json=False)
```

Exports the current plugin configuration to a file.

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

Enables results caching and disables auto-shutdown of plugins.

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

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

#### get_plugins()
```python
ifxlookup.IFXLookup.get_plugins(self)
```
Returns a map of plugins configured to use in the lookup.

#### lookup()
```python
ifxlookup.IFXLookup.lookup(self,subjects,filter=None)
```
Performs a search with the configured plugins and filter and returns a dictionary of search data.

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

Searches a given directory for compatible plugins and returns a map of available plugin names and classes. Useful for loading plugins from a directory.

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

Sets the debug level.

#### use_plugins(plugins,reload)
```python
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

Configuring the python module is similar to configuring the command line tool. Configurations consist of dictionaries with plugin names as the keys and are required for every plugin used in the lookup.

#### 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.

## Known issues with this version:

* Caching is not yet implemented
* VMWare plugins are not finished