Skip to content
Python API for the service.
Branch: master
Clone or download
Latest commit ea0df87 May 29, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
limacharlie Add support for a callback for auth. May 29, 2019
LICENSE Initial commit May 1, 2018
setup.cfg Version bump. May 20, 2019 Python API

This Python library is a simple abstraction to the REST API. For more information on For more information on the REST API:


Overview Usage

The Python API uses the REST API. The REST API currently supports many more functions. If the Python is missing a function available in the REST API that you would like to use, let us know at


pip install limacharlie


All APIs/modules accept specific Organization ID (OID) and API Keys programatically. However it is often convenient to provide those via environment variables or files. Therefore, if the OID and API Key provided is None, credentials will be acquired in the following order globally:

  1. LC_OID and LC_API_KEY environment variables.
  2. LC_CREDS_FILE environment variable points to a YAML file with oid: <OID> and api_key: <KEY>.
  3. Assumes a creds file (like #2) is present at ~/.limacharlie.

To set your credentials in your home directory's .limacharlie file, use limacharlie login, all future API / CLI commands in the future will automatically have access to those credentials.

The "login" mechanism supports multiple environments.

Listing environments:

limacharlie use

and then selecting a specific environment:

. <(limacharlue use my-home-org)

note the use of . <() to source the output from the use my-home-org command which outputs an export command.


import limacharlie

OID = 'Your-Org-ID'
API_KEY = 'Your-Secret-API-Key'

man = limacharlie.Manager( OID, API_KEY )
all_sensors = man.sensors()
sensor = all_sensors[ 0 ]
sensor.tag( 'suspicious', ttl = 60 * 10 )
sensor.task( 'os_processes' )
sensor.task( 'yara_scan -e *evil.exe ' + YARA_SIG )



This is a the general component that provides access to the managing functions of the API like querying sensors online, creating and removing Outputs etc.


The firehose is a simple object that listens on a port for data. Under the hood it creates a Syslog Output on pointing to itself and removes it on shutdown. Data from is added to firehose.queue (a gevent Queue) as it is received.

It is a basic building block of automation for


This is the object returned by manager.sensor( sensor_id ).

It supports a task, tag, untag and getTags functions. This is the main way to interact with a specific sensor.

Integrated Behavior

This mode is available by specifying an inv_id and is_interactive = True to a Manager object. It makes the Manager setup the relevant comms channels so that any Sensor objects it produces support the .request() function which behaves like the .task() function but it also returns a FutureResponses object that is a proxy for any responses from the task.

For a better idea on usage see the demo.

Command Line Usage

Some Python API classes support being executed directly from the command line to provide easier access to some of the capabilities.


limacharlie.Firehose event -n firehose_test -t fh_test --oid c82e5c17-d519-4ef5-a4ac-caa4a95d31ca

Listens on interface, port 9424 for incoming connections from Receives only events from hosts tagged with fh_test.


limacharlie.Spout event --oid c82e5c17-d519-4ef5-a4ac-caa4a95d31ca

Behaves similarly to the Firehose, but instead of listenning from an internet accessible port, it connects to the service to stream the output over HTTP. This means the Spout allows you to get ad-hoc output like the Firehose, but it also works through NATs and proxies.

It is MUCH more convenient for short term ad-hoc outputs, but it is less reliable than a Firehose for very large amounts of data.


limacharlie.Manager --oid c82e5c17-d519-4ef5-a4ac-caa4a95d31ca

Starting the Manager module directly starts an interactive shell to

Config Syncing

limacharlie.Sync fetch --oid c82e5c17-d519-4ef5-a4ac-c454a95d31ca

limacharlie.Sync push --dry-run --oid c82e5c17-d519-4ef5-a4ac-c454a95d31ca

The fetch command will get a list of the Detection & Response rules in your organization and will write them to the config file specified or the default config file LCConf in YAML format.

Then push can upload the rules specified in the config file (or the default one) to your organization. The optional --force argument will remove active rules not found in the config file. The --dry-run simulates the sync and displayes the changes that would occur.

The --config allows you to specify an alternate config file and the --api-key allows you to specify a file on disk where the API should be read from (otherwise, of if - is specified as a file, the API Key is read from STDIN).

All these capabilities are also supported directly by the limacharlie.Sync object.

The Sync functionality currently supports D&R rules as well as Outputs. The --no-rules and --no-outputs flags can be used to ignore one or the other in config files and sync.

To understand better the config format, do a fetch from your organization or have a look at the samples. Notice the use of the include statement. Using this statement you can combine multiple config files together, making it ideal for the management of complex rule sets and their versioning.

Spot Checks

limacharlie.SpotCheck --no-macos --no-linux --tags vip --file c:\\evil.exe

Used to perform Organization-wide checks for specific indicators of compromise. Available as a custom API SpotCheck object or as a module from the command line. Supports many types of IoCs like file names, directories, registry keys, file hashes and yara signatures.

For detailed usage: limacharlie.SpotCheck --help


You can’t perform that action at this time.