LimaCharlie.io Python API
This Python library is a simple abstraction to the LimaCharlie.io REST API. For more information on LimaCharlie.io: https://limacharlie.io. For more information on the REST API: https://api.limacharlie.io.
- Python API Doc: https://python-limacharlie.readthedocs.io/en/latest/
- General LimaCharlie Doc: http://doc.limacharlie.io/
The Python API uses the LimaCharlie.io 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 firstname.lastname@example.org.
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:
LC_CREDS_FILEenvironment variable points to a YAML file with
- Assumes a creds file (like #2) is present at
To set your credentials in your home directory's
.limacharlie file, use
python -m limacharlie login, all
future API / CLI commands in the future will automatically have access to those credentials.
The "login" mechanism supports multiple environments.
python -m limacharlie use
and then selecting a specific environment:
. <(python -m limacharlue use my-home-org)
note the use of
. <() to source the output from the
use my-home-org command which outputs an
import limacharlie OID = 'Your-Org-ID' API_KEY = 'Your-Secret-API-Key' YARA_SIG = 'https://raw.githubusercontent.com/Yara-Rules/rules/master/Malicious_Documents/Maldoc_PDF.yar' 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 LimaCharlie.io data.
Under the hood it creates a Syslog Output on limacharlie.io pointing to itself
and removes it on shutdown. Data from limacharlie.io is added to
gevent Queue) as it is received.
It is a basic building block of automation for limacharlie.io.
This is the object returned by
manager.sensor( sensor_id ).
It supports a
getTags functions. This
is the main way to interact with a specific sensor.
This mode is available by specifying an
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.
python -m limacharlie.Firehose 184.108.40.206:9424 event -n firehose_test -t fh_test --oid c82e5c17-d519-4ef5-a4ac-caa4a95d31ca
Listens on interface
9424 for incoming connections from LimaCharlie.io.
Receives only events from hosts tagged with
python -m 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
output.limacharlie.io 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.
python -m limacharlie.Manager --oid c82e5c17-d519-4ef5-a4ac-caa4a95d31ca
Manager module directly starts an interactive shell to limacharlie.io.
python -m limacharlie.Sync fetch --oid c82e5c17-d519-4ef5-a4ac-c454a95d31ca
python -m limacharlie.Sync push --dry-run --oid c82e5c17-d519-4ef5-a4ac-c454a95d31ca
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
LCConf in YAML format.
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.
--config allows you to specify an alternate config file and the
you to specify a file on disk where the API should be read from (otherwise, of if
specified as a file, the API Key is read from STDIN).
All these capabilities are also supported directly by the
The Sync functionality currently supports D&R rules as well as Outputs. The
--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
statement. Using this statement you can combine multiple config files together, making
it ideal for the management of complex rule sets and their versioning.
python -m 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
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:
python -m limacharlie.SpotCheck --help