Smithery is now a part of Arcade.dev! Read more in our announcement here
Help users integrate with LimaCharlie using the REST API, Python SDK, or Go SDK for programmatic access to sensors, detection rules, events, and platform features.
This skill provides comprehensive guidance for integrating with LimaCharlie programmatically using the REST API, Python SDK, or Go SDK. Use this skill when users need help with API authentication, SDK usage, event streaming, programmatic sensor management, or building custom integrations.
LimaCharlie provides three primary methods for programmatic access:
https://api.limacharlie.io
LimaCharlie uses JWT (JSON Web Tokens) for API authentication. There are two types of API keys:
Using curl:
curl -X POST "https://jwt.limacharlie.io" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "oid=YOUR_ORG_ID&secret=YOUR_API_KEY"
Response:
{
"jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
The JWT token is valid for 1 hour and must be refreshed after expiration.
API keys have granular permissions. Common permissions include:
sensor.get: Read sensor informationsensor.task: Send tasks to sensorssensor.tag: Add/remove sensor tagsdr.list: List detection rulesdr.set: Create/update detection rulesdr.del: Delete detection rulesoutput.*: Manage outputs (required for Firehose/Spout)View all available permissions: https://app.limacharlie.io/owner_permissions
API keys support "flair" tags to modify behavior:
[bulk]: Optimizes rate limits for high-volume API usageautomation-key[bulk][segment]: Limits visibility to resources created by this key onlythird-party-integration[segment]API keys are managed in the web interface: Organization > Access Management > REST API
pip install limacharlie
import limacharlie
manager = limacharlie.Manager(oid='YOUR_ORG_ID', secret_api_key='YOUR_API_KEY')
sensors = manager.sensors()
sensor = manager.sensor('SENSOR_ID')
sensor.task('os_processes')
See PYTHON.md for complete documentation.
go get github.com/refractionPOINT/go-limacharlie/limacharlie
import "github.com/refractionPOINT/go-limacharlie/limacharlie"
client := limacharlie.NewClient()
org := client.Organization(limacharlie.ClientOptions{})
sensors, err := org.ListSensors()
See GO.md for complete documentation.
IMPORTANT: When users provide relative time offsets (e.g., "last hour", "past 24 hours", "last week"), you MUST dynamically compute the current epoch timestamp based on the actual current time. Never use hardcoded or placeholder timestamps.
import time
# Compute current time dynamically
current_epoch_seconds = int(time.time())
current_epoch_milliseconds = int(time.time() * 1000)
The granularity (seconds vs milliseconds) depends on the specific API or MCP tool. Always check the tool signature or API documentation to determine which unit to use.
Example: "List artifacts from the last hour"
end_time = int(time.time()) # Current time
start_time = end_time - 3600 # 1 hour ago
# Use with API calls
artifacts.listArtifacts(start_time=start_time, end_time=end_time)
Common offsets (in seconds):
For millisecond-based APIs, multiply by 1000.
NEVER:
1234567890ALWAYS:
time.time()sensors = manager.sensors()
sensor = manager.sensor('SENSOR_ID')
sensor.addTag('production', ttl=3600)
sensor.removeTag('old-tag')
sensor.task('os_processes')
result = sensor.simpleRequest('os_info', timeout=30)
sensor.isolate()
sensor.rejoin()
from limacharlie import Hive, HiveRecord
hive = Hive(manager)
hive.set(HiveRecord(hive_name='dr-general', key='rule-name', data=rule_data))
| Feature | Spout | Firehose |
|---|---|---|
| Connection | Pull (HTTPS) | Push (requires open port) |
| NAT/Proxy | Works through NAT | Requires port forwarding |
| Reliability | Good for moderate volume | Best for high volume |
| Setup | Easier | More complex |
| Use case | Ad-hoc, development | Production, long-term |
spout = limacharlie.Spout(manager, data_type='detect', is_parse=True)
for detection in spout:
print(detection['detect_name'])
spout.shutdown()
firehose = limacharlie.Firehose(manager, listen_on='0.0.0.0:4443', data_type='event')
firehose.start()
See EXAMPLES.md and PYTHON.md for complete examples.
# System Information
'os_info' # Operating system details
'os_processes' # Running processes
'os_services' # Installed services
'os_packages' # Installed software
'os_autoruns' # Autostart programs
'os_drivers' # Loaded drivers (Windows)
# File Operations
'file_info PATH' # File metadata
'file_get PATH' # Download file
'file_hash PATH' # Calculate file hash
'file_del PATH' # Delete file
# Network Operations
'netstat' # Network connections
'dns_resolve DOMAIN' # DNS lookup
# Process Operations
'mem_map PID' # Process memory map
'kill PID' # Terminate process
# Forensics
'history_dump' # Event history
'hidden_module_scan' # Find hidden modules
[bulk] flair for high-volume operations# Use environment variables
manager = limacharlie.Manager() # Uses LC_OID and LC_API_KEY
# Check sensor status
if sensor.isOnline():
sensor.task('os_processes')
# Investigation tracking
manager = limacharlie.Manager(inv_id='incident-2024-001')
See TROUBLESHOOTING.md for detailed error handling.
| Endpoint | Method | Description |
|---|---|---|
/sensors/{oid} |
GET | List all sensors |
/sensor/{oid}/{sid} |
GET | Get specific sensor |
/sensor/{oid}/{sid}/task |
POST | Task a sensor |
/sensor/{oid}/{sid}/tag |
POST/DELETE | Manage sensor tags |
/rules/{oid} |
GET/POST | Manage detection rules |
/artifacts/{oid} |
POST | Upload artifact |
/artifacts/{oid}/{aid} |
GET | Download artifact |
/orgs/{oid} |
GET | Get organization info |
Manager: Main SDK entry point, organization managementSensor: Individual sensor operations and taskingHive: Key-value storage for D&R rules and dataSpout: Pull-based event streamingFirehose: Push-based event streamingArtifacts: Artifact upload/download managementlimacharlie.Client: Main client initializationlimacharlie.Organization: Organization operationslimacharlie.Sensor: Sensor management and taskinglimacharlie.CoreDRRule: Detection rule structurefirehose: Firehose streaming package[bulk] flair for high-volume API usage