limacharlie package¶

Submodules¶

limacharlie.Configs module¶

class limacharlie.Configs.Configs(oid=None, env=None, manager=None, isDontUseInfraService=False)¶

Bases: object

Configs object to fetch and apply configs to and from organizations.

fetch(toConfigFile, isRules=False, isFPs=False, isOutputs=False, isIntegrity=False, isArtifact=False, isExfil=False, isResources=False, isOrgConfigs=False, isHives={}, isInstallationKeys=False, isYara=False)¶

Retrieves the effective configuration in the cloud to a local config file.

Parameters:	toConfigFile (str, dict) – the path to the local config file or dict where to store config.

push(fromConfigFile, isForce=False, isDryRun=False, isIgnoreInaccessible=False, isRules=False, isFPs=False, isOutputs=False, isIntegrity=False, isArtifact=False, isExfil=False, isResources=False, isOrgConfigs=False, isHives={}, isInstallationKeys=False, isYara=False, isVerbose=False)¶

Apply the configuratiion in a local config file to the effective configuration in the cloud.

Parameters:

fromConfigFile (str/dict) – the path to the config file or dict of a config file content.
isForce (boolean) – if True will remove configurations in the cloud that are not present in the local file.
isDryRun (boolean) – if True will only simulate the effect of a push.
isIgnoreInaccessible (boolean) – if True, ignore inaccessible resources (locked) even when isForce is True.
isRules (boolean) – if True, push D&R rules.
isFPs (boolean) – if True, push False Positive rules.
isOutputs (boolean) – if True, push Outputs.
isIntegrity (boolean) – if True, push Integrity rules.
isArtifact (boolean) – if True, push Artifact rules.
isExfil (boolean) – if True, push Exfil rules.
isResources (boolean) – if True, push Resource subscriptions.
isOrgConfigs (boolean) – if True, push Org Configs.
(dict{"hive_name" (isHives) – true}): only one hive value is requried for sync push to process passed config data, if empty or null no push will occur
isInstallationKeys (boolean) – if True, push Installation Keys.
isYara (boolean) – if True, push Yara rules and sources.

Returns:

a generator of changes as tuple (changeType, dataType, dataName).

exception limacharlie.Configs.LcConfigException¶: Bases: exceptions.Exception

limacharlie.Firehose module¶

class limacharlie.Firehose.Firehose(manager, listen_on, data_type, public_dest=None, name=None, ssl_cert=None, ssl_key=None, is_parse=True, max_buffer=1024, inv_id=None, tag=None, cat=None, sid=None, is_delete_on_failure=False, on_dropped=None)¶

Bases: object

Listener object to receive data (Events, Detects or Audit) from a limacharlie.io Organization in push mode.

getDropped()¶: Get the number of messages dropped because queue was full.

resetDroppedCounter()¶: Reset the counter of dropped messages.

shutdown()¶: Stop receiving data and potentially unregister the Output (if created here).

limacharlie.Jobs module¶

class limacharlie.Jobs.Job(manager, data)¶

Bases: object

Representation of a Job created by Services.

delete()¶: Delete this job.

fetchDetails()¶: Fetch detailed activity for this job in the cloud.

isFinished()¶

Check if this job has terminated.

Returns:	True if the job is finished.

update()¶: Fetch any updates to the job found in the cloud.

limacharlie.Logs module¶

class limacharlie.Logs.Logs(manager, accessToken=None)¶

Bases: object

Helper object to upload External Logs to limacharlie.io without going through a sensor.

getOriginal(payloadId, filePath=None, fileObj=None, optParams={}, customGetter=None)¶

Download an orginal log.

Parameters:	payloadId (str) – the payload identifier to download. filePath (str) – optional path where to download the file to. fileObj (file obj) – optional file object where to write the log.

listArtifacts(type=None, source=None, originalPath=None, after=None, before=None, withData=False, optParams={}, customGetter=None)¶

Get the list of artifacts matching parameters.

Parameters:

type (str) – only list artifacts with type.
source (str) – only list artifacts from this source.
originalPath (str) – only list artifacts with this original path.
after (int) – list artifacts after a given second epoch.
before (int) – list artifacts before a given second epoch.
withData (bool) – if True, artifact will be downloaded inline and the return value will be a tuple (artifactRecord, localFilePath).

upload(filePath, source=None, hint=None, payloadId=None, allowMultipart=False, originalPath=None, nDaysRetention=30)¶

Upload a log.

Parameters:

filePath (str) – path to the file to upload.
source (str) – optional source identifier for where the log came from.
hint (str) – optional data format hint for the log.
payloadId (str) – optional unique payload identifier for the log, used to perform idempotent uploads.
allowMultipart (bool) – unused, if True will perform multi-part upload for large logs.
nDaysRetention (int) – number of days the data should be retained in the cloud.

limacharlie.Manager module¶

class limacharlie.Manager.Manager(oid=None, secret_api_key=None, environment=None, inv_id=None, print_debug_fn=None, is_interactive=False, extra_params={}, jwt=None, uid=None, onRefreshAuth=None, isRetryQuotaErrors=False)¶

Bases: object

General interface to a limacharlie.io Organization.

addApiKey(keyName, permissions=[])¶

Add an API key to an organization.

Parameters:	keyName (str) – name of the key to add. permissions (str[]) – list of permissions for the key.
Returns:	the secret value of the new API key.

addGroupMember(groupId, memberEmail)¶

Add a User as a member of a group.

Parameters:	groupId (str) – group id. memberEmail (str) – email to add.

addGroupOrg(groupId, oid)¶

Add an Org to a group.

Parameters:	groupId (str) – group id. oid (str) – organization id to add.

addGroupOwner(groupId, ownerEmail)¶

Add a new owner to a group.

Parameters:	groupId (str) – group id. ownerEmail (str) – email to add.

addUser(email)¶

Add a user to an organization.

Parameters:	email (str) – email of the user to add.

addUserPermission(email, permission)¶

Add a user to an organization.

Parameters:	email (str) – email of the user to add. permission (str) – permission to add to the user.

add_fp(name, rule, isReplace=False, ttl=None)¶

Add a False Positive rule to the Organization.

For detailed explanation and possible rules parameters see the official documentation, naming is the same as for the REST interface.

Parameters:	name (str) – name to give to the rule. isReplace (boolean) – if True, replace existing rule with the same name. detection (dict) – dictionary representing the False Positive rule content. ttl (int) – number of seconds before the rule should be auto-deleted.
Returns:	the REST API response (JSON).

add_output(name, module, type, **kwargs)¶

Add an Output to the Organization.

For detailed explanation and possible Output module parameters see the official documentation, naming is the same as for the REST interface.

Parameters:	name (str) – name to give to the Output. module (str) – name of the Output module to use. type (str) – type of Output stream. **kwargs – arguments specific to the Output module, see official doc.
Returns:	the REST API response (JSON).

add_rule(name, detection, response, isReplace=False, namespace=None, isEnabled=True, ttl=None)¶

Add a Rule to the Organization.

For detailed explanation and possible Rules parameters see the official documentation, naming is the same as for the REST interface.

Parameters:

name (str) – name to give to the Rule.
namespace (str) – optional namespace to operator on, defaults to “general”.
isReplace (boolean) – if True, replace existing Rule with the same name.
detection (dict) – dictionary representing the detection component of the Rule.
response (list) – list representing the response component of the Rule.
isEnabled (boolean) – if True (default), the rule is enabled.
ttl (int) – number of seconds before the rule should be auto-deleted.

Returns:

the REST API response (JSON).

configureUSPKey(name, parse_hint='', format_re='')¶

Set the USP configuration of an Ingestion key.

Parameters:	name (str) – name of the Ingestion key to configure.
Returns:	Dictionary with the key name and value.

createGroup(name)¶

Create a new group.

Parameters:	name (str) – group name.

createNewOrg(name, location, template=None)¶

Request the creation of a new organization.

Parameters:	name (str) – organization name. location (str) – location where the organization is created. template (str) – optional yaml template to initialize the new organization with.
Returns:	dict of info on new organization.

create_installation_key(tags, desc)¶

Create an installation key.

Parameters:	tags (list) – list of tags. desc (str) – description for the installation key.
Returns:	the REST API response (JSON).

delIngestionKey(name)¶

Delete an Ingestion key.

Parameters:	name (str) – name of the Ingestion key to delete.

del_fp(name)¶

Remove a False Positive rule from the Organization.

Parameters:	name (str) – the name of the rule to remove.
Returns:	the REST API response (JSON).

del_output(name)¶

Remove an Output from the Organization.

Parameters:	name (str) – the name of the Output to remove.
Returns:	the REST API response (JSON).

del_rule(name, namespace=None)¶

Remove a Rule from the Organization.

Parameters:	name (str) – the name of the Rule to remove. namespace (str) – optional namespace to operator on, defaults to “general”.
Returns:	the REST API response (JSON).

deleteGroup(groupId)¶

Delete a specific group.

Parameters:	groupId (str) – group id.

deleteOrg(oid, withConfirmation=None)¶

Request the deletion of an organization.

Deleting an organization means the total and unrecoverable deletion of ALL data associated.

This API is used in 2 steps: - Call this API without any “withConfirmation” value specified to get a confirmation token. - Using the confirmation token returned, call the same API with the token. Tokens are valid for 1 minute.

Parameters:	oid (str) – the organization id to delete. withConfirmation (str) – optional confirmation value returned by the call to the API without it.
Returns:	dict of info on new organization.

delete_installation_key(iid)¶

Delete an installation key.

Parameters:	iid (str) – installation key id.
Returns:	the REST API response (JSON).

exportSensorList()¶

Perform a bulk export of the entire sensor list.

Returns:	a dictionary of sensors with their information and tags.

fps()¶

Get the list of all False Positive rules for the Organization.

Returns:	a list of False Positive rules (JSON).

getAllTags()¶

Get a list of tags in use by sensors.

Returns:	a list of tags.

getApiKeys()¶: Get the list of API keys in the organization.

getAvailableServices()¶

Get the list of Services currently available.

Returns:	List of Service names.

getBatchObjectInformation(objects, isCaseSensitive=True)¶

Get object prevalence information in a batch.

Parameters:	objects (dict) – dictionary of object type to list of object names to query for (objects[“file_name”] = [“a.exe”, “b.exe”]). isCaseSensitive (bool) – False to ignore case in the object name.
Returns:	a dict with keys as time ranges and values are maps of object types to object name lists.

getGroup(groupId)¶

Get the details about a specific group.

Parameters:	groupId (str) – group id.
Returns:	dict of group details

getGroupLogs(groupId)¶

Get the audit logs for a group.

Parameters:	groupId (str) – group id.
Returns:	list of audit entries

getGroups()¶: Get all groups this User has access to as an owner.

getHistoricDetections(start, end, limit=None, cat=None)¶

Get the detections for this organization between the two times, requires Insight (retention) enabled.

Parameters:	start (int) – start unix (seconds) timestamp to fetch detects from. end (int) – end unix (seconds) timestamp to feth detects to. limit (int) – maximum number of detects to return. cat (str) – return dects only from this category.
Returns:	a generator of detects.

getIngestionKeys()¶

Get the Ingestion keys associated to this organization.

Returns:	Dictionary of the Ingestion keys.

getInsightHostCountPerPlatform()¶

Get the number of hosts for each platform for which we have long term Insight data.

Returns:	a dict with “mac”, “linux” and “windows” and their count tuples [1,7,30].

getJob(jobId)¶

Get a specific job.

Parameters:	jobId (str) – job ID of the job to get.
Returns:	a Job object.

getJobs(startTime, endTime, limit=None, sid=None)¶

Get all the jobs in an organization in a time window.

Parameters:	startTime (int) – second epoch of the start of the time window. endTime (int) – second epoch of the end of the time window. limit (int) – optional maximum number of jobs to return. sid (str) – optionally only return jobs that relate to this sensor ID.
Returns:	a Job object.

getObjectInformation(objType, objName, info, isCaseSensitive=True, isWithWildcards=False, limit=None, isPerObject=None)¶

Get information about an object (indicator) using Insight (retention) data.

Parameters:

objType (str) – the object type to query for, one of: user, domain, ip, hash, file_path, file_name.
objName (str) – the name of the object to query for, like “cmd.exe”.
info (str) – the type of information to query for, one of: summary, locations.
isCaseSensitive (bool) – False to ignore case in the object name.
isWithWildcards (bool) – True to enable use of “%” wildcards in the object name.
limit (int) – optional maximum number of sensors/logs to report, or None for LimaCharlie default.
isPerObject (bool) – if set, specifies if the results should be groupped per object when a wildcard is present.

Returns:

a dict with the requested information.

getOrgConfig(configName)¶

Get the value of a per-organization config.

Parameters:	configName (str) – name of the config to get.
Returns:	String value of the configuration.

getOrgURLs()¶

Get the URLs used by various resources in the organization.

Returns:	Dictionary of resource types to URLs.

getSchema(name)¶

Get a specific Schema Definition.

Returns:	a Schema Definition for the given Schema Name.

getSchemas()¶

Get the list of all Schemas available for the Organization.

Returns:	a list of Schema names.

getSensorsWithHostname(hostnamePrefix, as_dict=False)¶

Get the list of sensor IDs and hostnames that match the given prefix.

Parameters:	hostnamePrefix (str) – a hostname prefix to search for.
Returns:	List of (sid, hostname).

getSensorsWithIp(ip, start, end)¶

Get the list of sensor IDs that used the given IP during the time range.

Parameters:	ip (str) – the IP address used. start (int) – beginning of the time range to look for. end (int) – end of the time range to look for.
Returns:	List of sid.

getSubscriptions()¶: Get the list of resources the organization is subscribed to.

getUsageStats()¶

Get general usage stats for the org.

Parameters:	tags (list) – list of tags. desc (str) – description for the installation key.
Returns:	the REST API response (JSON).

getUserPermissions()¶: Get the list of users and their permissions.

getUsers()¶: Get the list of users in the organization.

get_installation_key(iid)¶

Get a single installation key by ID.

Parameters:	name (str) – installation key id to get.
Returns:	the REST API response (JSON).

get_installation_keys()¶

Get all installation keys for the Organization.

Returns:	the REST API response (JSON).

hosts(hostname_expr, as_dict=False)¶

Get the Sensor objects for hosts matching a hostname expression.

Parameters:	hostname_expr (str) – hostname prefix to look for.
Returns:	a list of Sensor IDs matching the hostname expression.

isInsightEnabled()¶

Check to see if Insight (retention) is enabled on this organization.

Returns:	True if Insight is enabled.

make_interactive()¶: Enables interactive mode on this instance if it was not created with is_interactive.

outputs()¶

Get the list of all Outputs configured for the Organization.

Returns:	a list of Output descriptions (JSON).

removeApiKey(keyHash)¶

Remove an API key from an organization.

Parameters:	keyHash (str) – key hash of the key to remove.

removeGroupMember(groupId, memberEmail)¶

Remove a User from a group.

Parameters:	groupId (str) – group id. memberEmail (str) – email to remove.

removeGroupOrg(groupId, oid)¶

Remove an Org from a group.

Parameters:	groupId (str) – group id. oid (str) – organization id to remove.

removeGroupOwner(groupId, ownerEmail)¶

Remove an owner from the group.

Parameters:	groupId (str) – group id. ownerEmail (str) – email to remove.

removeUser(email)¶

Remove user from an organization.

Parameters:	email (str) – email of the user to remove.

removeUserPermission(email, permission)¶

Remove user from an organization.

Parameters:	email (str) – email of the user to remove. permission (str) – permission to remove from the user.

resetSchemas()¶: Reset the Schema Definition for all Schemas in an Organization.

rules(namespace=None)¶

Get the list of all Detection & Response rules for the Organization.

Parameters:	namespace (str) – optional namespace to operator on, defaults to “general”.
Returns:	a list of D&R rules (JSON).

sensor(sid, inv_id=None)¶

Get a Sensor object for the specific Sensor ID.

The sensor may or may not be online.

Parameters:	sid (uuid str) – the Sensor ID to represent. inv_id (str) – investigation ID to add to all actions done using this object.
Returns:	a Sensor object.

sensors(inv_id=None, selector=None)¶

Gets all Sensors in the Organization.

The sensors may or may not be online.

Parameters:	inv_id (str) – investigation ID to add to all actions done using these objects. selector (str) – sensor selector expression to use as filter.
Returns:	a generator of Sensor objects.

sensorsWithTag(tag)¶

Get a list of sensors that have the matching tag.

Parameters:	tag (str) – a tag to look for.
Returns:	a list of Sensor objects.

serviceRequest(serviceName, data, isAsynchronous=False, isImpersonate=False)¶

Issue a request to a Service.

Parameters:	serviceName (str) – the name of the Service to task. data (dict) – JSON data to send to the Service as a request. isAsynchronous (bool) – if set to False, wait for data from the Service and return it. isImpersonate (bool) – if set to True, request the Service impersonate the caller.
Returns:	Dict with general success, or data from Service if isSynchronous.

setGroupPermissions(groupId, permissions=[])¶

Set the permissions for Users in the group.

Parameters:	groupId (str) – group id. permissions (list of str) – list of permissions.

setIngestionKey(name)¶

Set (or reset) an Ingestion key.

Parameters:	name (str) – name of the Ingestion key to set.
Returns:	Dictionary with the key name and value.

setOrgConfig(configName, value)¶

Set the value of a per-organization config.

Parameters:	configName (str) – name of the config to get. value (str) – value of the config to set.

setOrgQuota(quota)¶

Set a new sensor quota for the organization.

Parameters:	quota (int) – the new quota value.

setSensorVersion(isFallbackVersion=False, isSleepVersion=False, specificVersion=None)¶

Set the sensor version for an Organization.

Parameters:	isFallbackVersion (bool) – use the “stable” version. isSleepVersion (bool) – set sensors in dormant mode. specificVersion (str) – set a specific sensor version.

shutdown()¶: Shut down any active mechanisms like interactivity.

subscribeToResource(name)¶

Subscribe the organization to the specific resource.

Parameters:	name (str) – name of the resource like lookup/test-res.

testAuth(permissions=[])¶

Tests authentication with limacharlie.io.

Parameters:	permissions (list) – optional list of permissions validate we have.
Returns:	a boolean indicating whether authentication succeeded.

unsubscribeFromResource(name)¶

Unsubscribe the organization from the specific resource.

Parameters:	name (str) – name of the resource like lookup/test-res.

userAccessibleOrgs()¶

Query the API with a User API to see which organizations the user has access to.

Returns:	A dict with org OIDs and names.

whoAmI()¶

Query the API to see which organizations we are authenticated for.

Returns:	A list of organizations and permissions, or a dictionary of organizations with the related permissions.

limacharlie.Payloads module¶

class limacharlie.Payloads.Payloads(manager)¶

Bases: object

Helper object to manage executable Payloads for sensors.

create(name, payloadPath=None, payloadContent=None)¶

Create a new payload.

Parameters:	name (str) – the name of the payload to create. payloadPath (str) – path to the file containing the payload. payloadContent (bytes) – content of the new payload.

delete(name)¶

Delete a payload.

Parameters:	name (str) – the name of the payload to delete.

get(name)¶

Get a specific payload content.

Parameters:	name (str) – the name of the payload to get.

list()¶: List all available payloads.

limacharlie.Replay module¶

class limacharlie.Replay.Replay(manager)¶

Bases: object

Interface to query historical sensor data in Insight with specific D&R rules.

scanEntireOrg(startTime, endTime, ruleName=None, namespace=None, ruleContent=None, isRunTrace=False, limitEvent=None, limitEval=None, isStateful=None, isDryRun=False)¶

Scan an entire organization’s data with a D&R rule.

Parameters:

startTime (int) – seconds epoch to start scanning at.
endTime (int) – seconds epoch to stop scanning at.
ruleName (str) – the name of an existing D&R rule to use.
namespace (str) – the namespace the ruleName lives in.
ruleContent (dict) – D&R rule to use to scan, with a “detect” key and a “respond” key.
isRunTrace (bool) – if True, generate a trace of the evaluation.
limitEvent (int) – approximately limit the number of events evaluated.
limitEval (int) – approximately limit the number of rule evaluations.
isIgnoreState (bool) – if True, parallelize processing of single sensors to increase performance but limit effectiveness of stateful detection.

Returns:

a dict containing results of the query.

scanEvents(events, ruleName=None, namespace=None, ruleContent=None, isRunTrace=False, limitEvent=None, limitEval=None, isDryRun=False)¶

Scan the specific events with a D&R rule.

Parameters:

events (list) – list of events to scan.
ruleName (str) – the name of an existing D&R rule to use.
namespace (str) – the namespace the ruleName lives in.
ruleContent (dict) – D&R rule to use to scan, with a “detect” key and a “respond” key.
isRunTrace (bool) – if True, generate a trace of the evaluation.
limitEvent (int) – approximately limit the number of events evaluated.
limitEval (int) – approximately limit the number of rule evaluations.

Returns:

a dict containing results of the query.

scanHistoricalSensor(sid, startTime, endTime, ruleName=None, namespace=None, ruleContent=None, isRunTrace=False, limitEvent=None, limitEval=None, isStateful=None, isDryRun=False)¶

Scan a specific sensor’s data with a D&R rule.

Parameters:

sid (str) – sensor ID to scan.
startTime (int) – seconds epoch to start scanning at.
endTime (int) – seconds epoch to stop scanning at.
ruleName (str) – the name of an existing D&R rule to use.
namespace (str) – the namespace the ruleName lives in.
ruleContent (dict) – D&R rule to use to scan, with a “detect” key and a “respond” key.
isRunTrace (bool) – if True, generate a trace of the evaluation.
limitEvent (int) – approximately limit the number of events evaluated.
limitEval (int) – approximately limit the number of rule evaluations.
isIgnoreState (bool) – if True, parallelize processing of single sensors to increase performance but limit effectiveness of stateful detection.

Returns:

a dict containing results of the query.

validateRule(ruleContent)¶

Validate a D&R rule compiles properly.

Parameters:	ruleContent (dict) – D&R rule to use to scan, with a “detect” key and a “respond” key.
Returns:	a dict containing results of the query.

limacharlie.Replicants module¶

class limacharlie.Replicants.Dumper(manager)¶

Bases: limacharlie.Replicants._Replicant

Memory dumper service object.

dump(sid)¶

Dump the full memory of a given host.

Parameters:	sid (str) – sensor ID to sweep.

class limacharlie.Replicants.Exfil(manager)¶

Bases: limacharlie.Replicants._Replicant

Exfil control service manager object.

addEventRule(ruleName, events=[], tags=[], platforms=[])¶

Add an event rule describing events sent to the cloud in real-time.

Parameters:	ruleName (str) – name of the rule to add. events (list of str) – list of event names to send in real-time. tags (list of str) – list of tags sensors must posses for this rule to apply. platforms (list of str) – list of platform names this applies to.

addWatchRule(ruleName, event, operator, value, path=[], tags=[], platforms=[])¶

Add a watch rule to send matching events to the cloud in real-time.

Parameters:

ruleName (str) – name of the watch rule to add.
event (str) – name of the event this rule applies to.
operator (str) – comparison operator name to determine match.
value (str) – value to compare to for matching.
path (list of str) – path within the event to compare the value of, without a leading “event”.
tags (list of str) – list of tags sensors must posses for this rule to apply.
platforms (list of str) – list of platform names this applies to.

getRules()¶

Get the exfil rules in effect.

Returns:	Dict of rules.

removeEventRule(ruleName)¶

Remove an event rule.

Parameters:	ruleName (str) – name of the rule to remove.

removeWatchRule(ruleName)¶

Remove a watch rule.

Parameters:	ruleName (str) – name of the rule to remove.

class limacharlie.Replicants.Integrity(manager)¶

Bases: limacharlie.Replicants._Replicant

File and Registry Integrity Monitoring (FIM) service manager object.

addRule(ruleName, patterns=[], tags=[], platforms=[])¶

Add an FIM rule.

Parameters:	ruleName (str) – name of the rule to add. patterns (list of str) – list of file/registry patterns to monitor. tags (list of str) – list of tags sensors must posses for this rule to apply. platforms (list of str) – list of platform names this rule applies to.

getRules()¶

Get FIM rules in effect.

Returns:	Dict of rules.

removeRule(ruleName)¶

Remove an FIM rule.

Parameters:	ruleName (str) – name of the rule to remove.

class limacharlie.Replicants.Logging(manager)¶

Bases: limacharlie.Replicants._Replicant

Logging service manager object.

addRule(ruleName, patterns=[], tags=[], platforms=[], isDeleteAfter=False, isIgnoreCert=False, daysRetention=0)¶

Add a Log collection rule.

Parameters:

ruleName (str) – name of the rule to add.
patterns (list of str) – list of file patterns describing Logs to monitor and retrieve.
tags (list of str) – list of tags sensors must posses for this rule to apply.
platforms (list of str) – list of platform names this rule applies to.
isDeleteAfter (bool) – if True, delete the Log after retrieval.
isIgnoreCert (bool) – if True, sensor ignores SSL cert errors during log upload.

getRules()¶: Get the Log collection rules in effect.

removeRule(ruleName)¶

Remove a Log collection rule.

Parameters:	ruleName (str) – name of the rule to remove.

class limacharlie.Replicants.ReliableTasking(manager)¶

Bases: limacharlie.Replicants._Replicant

Reliable Tasking service object.

getTasks(sid=None, tag=None)¶

Issue a task for a set of sensors even if offline.

Parameters:	sid (str) – optional sensor ID to get the tasks for or ‘’ for all. tag* (str) – optional tag to select sensors to get the tasks for.

task(task, sid=None, tag=None, ttl=None)¶

Issue a task for a set of sensors even if offline.

Parameters:	task (str) – actual task command line to send. sid (str) – optional sensor ID to task or ‘’ for all. tag* (str) – optional tag to select sensors to send the task to. ttl (int) – optional number of seconds before unsent tasks expire, defaults to a week.

class limacharlie.Replicants.Replay(manager)¶

Bases: limacharlie.Replicants._Replicant

Replay service manager object.

runJob(startTime, endTime, sid=None, ruleName=None, ruleContent=None)¶

Run a Replay service job.

Parameters:	startTime (int) – epoch start time to replay. endTime (int) – epoch end time to replay. sid (str) – sensor ID to replay the data from. ruleName (str) – optional name of an existing D&R rule to replay. ruleContent (dict) – optional content of a D&R rule to replay.

class limacharlie.Replicants.Responder(manager)¶

Bases: limacharlie.Replicants._Replicant

Responder service manager object.

sweep(sid)¶

Perform a sweep of a given host.

Parameters:	sid (str) – sensor ID to sweep.

class limacharlie.Replicants.Yara(manager)¶

Bases: limacharlie.Replicants._Replicant

Yara service manager object.

addRule(ruleName, sources=[], tags=[], platforms=[])¶

Add a constant Yara scanning rule.

Parameters:	ruleName (str) – name of the rule to add. sources (list of str) – list of sources this rule should scan with. tags (list of str) – list of tags sensors must posses for this rule to apply. platforms (list of str) – list of platform names this rule applies to.

addSource(sourceName, source)¶

Add a Yara signature source.

Parameters:	sourceName (str) – name of the source to add. source (str) – source URL for the Yara signature(s).

getRules()¶

Get the constant Yara scanning rules in effect.

Returns:	Dict of rules.

getSource(sourceName)¶

Get the content of a Yara signature source.

Parameters:	sourceName (str) – name of the source to get.
Returns:	Source content.

getSources()¶

Get the Yara signature sources.

Returns:	Dict of sources.

removeRule(ruleName)¶

Remove a constant Yara scanning rule.

Parameters:	ruleName (str) – name of the rule to remove.

removeSource(sourceName)¶

Remove a Yara rule source.

Parameters:	sourceName (str) – name of the source to remove.

scan(sid, sources)¶

Perform an ad-hoc scan of a sensor with Yara signatures.

Parameters:	sid (str) – sensor ID to scan. sources (list of str) – list of source Yara signature names to use in the scan.

limacharlie.Search module¶

class limacharlie.Search.Search(environments=None, output='-')¶

Bases: object

Helper object to perform cross-organization IOC searches.

query(iocType, iocName, info, isCaseInsensitive=False, isWithWildcards=False, limit=None, isPerIoc=False)¶

Performa a search.

Parameters:

iocType (str) – type of IOC to search for.
iocName (str) – name of the IOC to search for.
info (str) – information type to retrieve.
isCaseInsensitive (bool) – if True, search for IOC in a case insensitive way.
isWithWildcards (bool) – if True, use “%” as a wildcard in the IOC name.
limit (int) – optional maximum number of sensors/logs to report about, otherwise defaults to internal LimaCharlie limit.
isPerIoc (bool) – if the search has wildcards, return results grouped per individual ioc.

Returns:

Dict of requested information.

limacharlie.Sensor module¶

class limacharlie.Sensor.Sensor(manager, sid)¶

Bases: object

Representation of a limacharlie.io Sensor.

delete()¶: Delete the sensor. It will not be able to connect to the cloud anymore, but will not be uninstalled.abs

getChildrenEvents(atom)¶

Get all children events from a given atom.

Parameters:	atom (string) – atom to get the children of.
Returns:	List of events.

getHistoricEvents(start, end, limit=None, eventType=None, isForward=True, outputName=None)¶

Get the events for this sensor between the two times, requires Insight (retention) enabled.

Parameters:	start (int) – start unix (seconds) timestamp to fetch events from. end (int) – end unix (seconds) timestamp to feth events to. limit (int) – maximum number of events to return. eventType (str) – return events only of this type. isForward (bool) – return events in ascending order. outputName (str) – send data to a named output instead.
Returns:	a generator of events.

getHistoricOverview(start, end)¶

Get a list of timestamps representing where sensor data is available in Insight (retention).

Parameters:	start (int) – start unix (seconds) timestamp to look for events from. end (int) – end unix (seconds) timestamp to look for events to.
Returns:	a list of timestamps.

getInfo()¶

Get basic information on the Sensor.

Returns:	high level information on the Sensor.

getObjectTimeline(start, end, bucketing='day', onlyTypes=None)¶

Get summarized information about timeline of Objects (IOCs) for this host.

Parameters:	start (int) – start time (unix seconds epoch) of the period to search. end (int) – end time (unix seconds epoch) of the period to search. bucketing (str) – granularity of the timeline, one of “hour”, “day”, “week”, “month”. onlyTypes (list) – list of object types to look for, all if undefined.
Returns:	Dict of timelines per type and object.

getRetainedEventCount(startTime, endTime, isDetailed=False)¶

Get the number of events retained for a given sensor between two second epochs.

Parameters:	startTime (int) – time (unix seconds epoch) of the period start. endTime (int) – time (unix seconds epoch) of the period end.
Returns:	Event counts.

getTags()¶

Get Tags applied to the Sensor.

Returns:	the list of Tags currently applied.

hostname()¶

Get the hostname of this sensor.

Returns:	a string of the hostname.

isChrome()¶

Checks if the sensor is on Chrome.

Returns:	True if the sensor is Chrome.

isChromeOS()¶

Checks if the sensor is on ChromeOS.

Returns:	True if the sensor is on ChromeOS.

isDataAvailableFor(timestamp)¶

Check if data is available in Insight for this sensor at this specific time.

Parameters:	timestamp (int) – time (unix seconds epoch) to check for events.
Returns:	True if data is available.

isIsolatedFromNetwork()¶

Determine if the given sensor is marked to be isolated from the network.

Returns:	True if isolated.

isLinux()¶

Checks if the sensor is a Linux OS.

Returns:	True if the sensor is Linux.

isMac()¶

Checks if the sensor is a Mac OS.

Returns:	True if the sensor is Mac.

isOnline()¶

Checks if the sensor is currently online.

Returns:	True if the sensor is connected to the cloud right now.

isWindows()¶

Checks if the sensor is a Windows OS.

Returns:	True if the sensor is Windows.

isolateNetwork()¶: Mark the sensor for network isolation (persistent).

rejoinNetwork()¶: Remove the sensor from network isolation (persistent).

request(tasks)¶

Send a task (or list of tasks) to the Sensor and returns a FutureResults where the results will be sent; requires Manager is_interactive.

Parameters:	tasks (str or list of str) – tasks to send in the command line format described in official documentation.
Returns:	a FutureResults object.

setInvId(inv_id)¶

Set an investigation ID to be applied to all actions done using the object.

Parameters:	inv_id (str) – investigation ID to propagate.

simpleRequest(tasks, timeout=30, until_completion=False)¶

Make a request to the sensor assuming a single response.

Parameters:	tasks (str or list of str) – tasks to send in the command line format described in official documentation. timeout (int) – number of seconds to wait for responses. until_completion (bool or callback) – if True, wait for completion receipts from the sensor, or callback for each response.
Returns:	a single event (if tasks was a single task), a list of events (if tasks was a list), or None if not received.

tag(tag, ttl=None)¶

Apply a Tag to the Sensor.

Parameters:	tag (str or list of str) – Tag(s) to apply. ttl (int) – number of seconds the Tag should remain applied.
Returns:	the REST API response (JSON).

task(tasks, inv_id=None)¶

Send a task (or list of tasks) to the Sensor.

Parameters:	tasks (str or list of str) – tasks to send in the command line format described in official documentation. inv_id (str) – investigation ID to propagate.
Returns:	the REST API response (JSON).

untag(tag)¶

Remove a Tag from the Sensor.

Parameters:	tag (str) – Tag to remove.
Returns:	the REST API response (JSON).

waitToComeOnline(timeout)¶

Wait for the sensor to be online.

Parameters:	timeout (int) – number of seconds to wait up to
Returns:	True if sensor is back or False if timeout

limacharlie.SpotCheck module¶

class limacharlie.SpotCheck.SpotCheck(oid, secret_api_key, cb_check, cb_on_start_check=None, cb_on_check_done=None, cb_on_offline=None, cb_on_error=None, n_concurrent=1, n_sec_between_online_checks=60, extra_params={}, is_windows=True, is_linux=True, is_macos=True, is_chrome=True, tags=None)¶

Bases: object

Representation of the process of looking for various Indicators of Compromise on the fleet.

start()¶: Start the SpotCheck process, returns immediately.

stop()¶: Stop the SpotCheck process, returns once activity has stopped.

wait(timeout=None)¶

Wait for SpotCheck to be complete, or timeout occurs.

Parameters:	timeout (float) – if specified, number of seconds to wait for SpotCheck to complete.
Returns:	True if SpotCheck is finished, False if a timeout was specified and reached before the SpotCheck is done.

limacharlie.Spout module¶

class limacharlie.Spout.Spout(man, data_type, is_parse=True, max_buffer=1024, inv_id=None, tag=None, cat=None, sid=None, extra_params={})¶

Bases: object

Listener object to receive data (Events, Detects or Audit) from a limacharlie.io Organization in pull mode.

getDropped()¶: Get the number of messages dropped because queue was full.

registerFutureResults(tracking_id, future, ttl=3600)¶

Register a FutureResults to receive events coming with a specific tracking ID and investigation ID.

Parameters:	tracking_id (str) – the full value of the investigation_id field to match on, including the custom tracking after the “/”. future (limacharlie.FutureResults) – future to receive the events. ttl (int) – number of seconds this future should be tracked.

resetDroppedCounter()¶: Reset the counter of dropped messages.

shutdown()¶: Stop receiving data.

limacharlie.Webhook module¶

class limacharlie.Webhook.Webhook(secret_key)¶

Bases: object

Helper class for various activities related to webhooks from limacharlie.io.

isSignatureValid(dataFromHook, signature)¶

Validate the signature from a webhook.

Parameters:	dataFromHook (str) – string found in the “data” element from the webhook. signature (str) – signature from the “Lc-Signature” header of the webhook.
Returns:	a boolean where True means the webhook data and signature are valid.

limacharlie.utils module¶

class limacharlie.utils.FutureResults¶

Bases: object

Represents a Future promise of results from a task sent to a Sensor.

getNewResponses(timeout=None)¶

Get new responses available, blocking for up to timeout seconds.

Parameters:	timeout (float) – number of seconds to block for new results.
Returns:	a list of new results, or an empty list if timeout is reached.

exception limacharlie.utils.LcApiException¶

Bases: exceptions.Exception

Exception type used for various errors in the LimaCharlie SDK.

limacharlie.utils.enhanceEvent(evt)¶

Wrap an event with an _enhancedDict providing utility functions getOne() and getAll().

Parameters:	evt (dict) – event to wrap.
Returns:	wrapped event.

limacharlie.utils.parallelExec(f, objects, timeout=None, maxConcurrent=None)¶

Execute a function on a list of objects in parallel.

Parameters:	f (callable) – function to apply to each object. objects (iterable) – list of objects to apply the function on. timeout (int) – maximum number of seconds to wait for collection of calls. maxConcurrent (int) – maximum number of function application to do concurrently.
Returns:	list of return values (or Exception if an exception occured).

Module contents¶

limacharlie API for limacharlie.io