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