Adapters

Adapters

How to work with LimaCharlie adapters — the telemetry ingestion layer for third-party data sources.

Adapter Categories

CLI Commands

Cloud Sensors

# List
limacharlie cloud-adapter list --oid <oid> --output yaml

# Get configuration
limacharlie cloud-adapter get --key <name> --oid <oid> --output yaml

# Create/Update
cat > /tmp/config.yaml << 'EOF'
<configuration>
EOF
limacharlie cloud-adapter set --key <name> --input-file /tmp/config.yaml --oid <oid> --output yaml

# Delete
limacharlie cloud-adapter delete --key <name> --confirm --oid <oid>

External Adapters

# List
limacharlie external-adapter list --oid <oid> --output yaml

# Get configuration
limacharlie external-adapter get --key <name> --oid <oid> --output yaml

# Create/Update
limacharlie external-adapter set --key <name> --input-file /tmp/config.yaml --oid <oid> --output yaml

# Delete
limacharlie external-adapter delete --key <name> --confirm --oid <oid>

Configuration Structure

All adapters share a common client_options structure:

client_options:
  identity:
    oid: "<organization-id>"
    installation_key: "<iid>"  # UUID format, or hive://secret/...
  platform: "text|json|gcp|aws|..."
  sensor_seed_key: "<unique-identifier>"
  hostname: "<adapter-hostname>"
  mapping:
    parsing_grok:
      message: '%{PATTERN:field} ...'
    event_type_path: "field/path"
    event_time_path: "timestamp/path"
    sensor_hostname_path: "host/path"

Key Config Fields

Credential References

Use Hive secrets for sensitive values:

apikey: "hive://secret/okta-api-key"
client_secret: "hive://secret/azure-client-secret"

Indexing Configuration

Enable IOC searching on adapter data:

indexing:
  - events_included: ["*"]
    path: "src_ip"
    index_type: "ip"
  - events_included: ["*"]
    path: "user/email"
    index_type: "user"

Supported index types: file_hash, file_path, file_name, domain, ip, user, service_name, package_name.

Parsing Validation

Validate parsing rules before deployment:

cat > /tmp/usp-test.yaml << 'EOF'
parsing_grok:
  message: "%{TIMESTAMP_ISO8601:timestamp} %{WORD:action} ..."
event_type_path: action
event_time_path: timestamp
sample_data:
  - "2025-01-15T10:30:00Z LOGIN user@example.com"
EOF
limacharlie usp validate --platform text --input-file /tmp/usp-test.yaml --oid <oid> --output yaml

Common Adapter Types

Microsoft sources (Defender, M365, Entra ID, Azure, WEL/EVTX): the platform follows the feed, not the product, and each feed has a purpose-built parser — never default to json. Resolve the exact adapter type + platform pairing against the "Microsoft Source → Adapter + Platform Selection" table in ${CLAUDE_PLUGIN_ROOT}/CONSTANTS.md before configuring.

On-Prem Deployment

Docker

docker run -d --rm -p 514:514/udp refractionpoint/lc-adapter syslog \
  client_options.identity.installation_key=<IID> \
  client_options.identity.oid=<OID> \
  client_options.platform=text \
  client_options.sensor_seed_key=<key> \
  port=514 is_udp=true

Binary

./lc_adapter syslog \
  client_options.identity.installation_key=<IID> \
  client_options.identity.oid=<OID> \
  client_options.platform=text \
  client_options.sensor_seed_key=<key> \
  port=514 is_udp=true

Researching Adapter Types

For unknown or undocumented adapters, check the usp-adapters repository:

# List available adapter implementations
WebFetch(url="https://api.github.com/repos/refractionPOINT/usp-adapters/contents")

# Read adapter config struct (usually client.go)
WebFetch(url="https://raw.githubusercontent.com/refractionPOINT/usp-adapters/master/<adapter>/client.go")

Post-Deployment Verification

Check Sensor Appeared

limacharlie sensor list --selector "iid == \`<iid>\`" --oid <oid> --output yaml

Check for Errors

# Adapter-specific errors
limacharlie external-adapter get --key <name> --oid <oid> --output yaml
# Look for last_error in sys_mtd

# Organization-wide errors
limacharlie org errors --oid <oid> --output yaml

Verify Data Flow

start=$(date -d '1 hour ago' +%s) && end=$(date +%s)
limacharlie event list --sid <sensor-id> --start $start --end $end --oid <oid> --output yaml

Common Pitfalls

1. IID vs Installation Key: Use the IID (UUID format), not the full base64 installation key
2. Grok field name: Always use message as the key in parsing_grok for text platform
3. DATESTAMP formats: TIMESTAMP_ISO8601 for ISO dates, SYSLOGTIMESTAMP for syslog, DATESTAMP for MM-DD-YY
4. Azure Event Hub: Connection string must include EntityPath=<event-hub-name>
5. Unparsed events: event_type: "unknown_event" with only text field means parsing is misconfigured
6. Credential storage: Always use hive://secret/<name> for production credentials