test-limacharlie-adapter

What this skill does

# Test LimaCharlie Adapter

Deploy a temporary LimaCharlie Adapter on the local Linux or Mac OS host for testing log ingestion. The adapter streams local logs to your LimaCharlie organization in real-time.

---

## LimaCharlie Integration

> **Prerequisites**: Run `/init-lc` to initialize LimaCharlie context.

### LimaCharlie CLI Access

All LimaCharlie operations use the `limacharlie` CLI directly:

```bash
limacharlie <noun> <verb> --oid <oid> --output yaml [flags]
```

For command help and discovery: `limacharlie <command> --ai-help`

### Critical Rules

| Rule | Wrong | Right |
|------|-------|-------|
| **CLI Access** | Call MCP tools or spawn api-executor | Use `Bash("limacharlie ...")` directly |
| **Output Format** | `--output json` | `--output yaml` (more token-efficient) |
| **Filter Output** | Pipe to jq/yq | Use `--filter JMESPATH` to select fields |
| **LCQL Queries** | Write query syntax manually | Use `limacharlie ai generate-query` first |
| **Timestamps** | Calculate epoch values | Use `date +%s` or `date -d '7 days ago' +%s` |
| **OID** | Use org name | Use UUID (call `limacharlie org list` if needed) |
| **Parsing** | Write Grok patterns manually | Use `parsing-helper` skill (identifies timezone requirements) |

---

This skill includes a **helper script** (`lc-adapter-helper.sh`) that handles all platform detection, downloading, and process management automatically.

## When to Use

Use this skill when:

- **Testing log ingestion**: Validate that logs flow correctly into LimaCharlie
- **Testing D&R rules on logs**: Write and test detection rules against real log data
- **Exploring adapter behavior**: Understand how adapters forward log data
- **Development and debugging**: Test adapter configurations before production deployment
- **Learning**: Explore LimaCharlie's log ingestion capabilities hands-on

## What This Skill Does

This skill performs a multi-phase deployment:

1. **Phase 1 - Installation Key**: Creates or finds an existing "Test Adapter" installation key in your selected LimaCharlie organization
2. **Phase 2 - Sample Collection & Parsing**: Captures sample logs and invokes the `parsing-helper` skill to generate and validate Grok patterns
3. **Phase 3 - Adapter Deployment**: Downloads the appropriate adapter binary for your platform and runs it with logs piped to stdin, using the parsing configuration from Phase 2
4. **Phase 4 - Verification**: Verifies the adapter is connected and appearing as a sensor
5. **Phase 5 - View Data**: Query and view the parsed ingested data

The adapter:
- Runs in the background (non-blocking)
- Uses a unique temp directory (avoids file conflicts)
- Streams logs in real-time (`journalctl -f` or `tail -f` on Linux, `log stream` on Mac OS)
- Does NOT require root/sudo
- Cleans up automatically when stopped

## Required Information

Before starting, ensure you have:

- **LimaCharlie organization**: Select from your available orgs or create a new one
- **Linux or Mac OS host**: Supports Linux x64, Mac Intel (x64), and Mac Apple Silicon (arm64)
- **Internet access**: Required to download the adapter binary
- **Log access**: On Linux with journalctl, uses system journal (preferred). On Linux without journalctl, needs read access to log files in `/var/log`. On Mac OS, uses the unified logging system via `log stream`

## How to Use

### Pre-requisite: Select an Organization

First, get the list of available organizations:

```bash
limacharlie org list --output yaml
```

This returns your available organizations. Use AskUserQuestion to let the user select one, or if they need a new org, use `limacharlie org create` to create one.

### Phase 1: Get or Create Installation Key

Check for existing "Test Adapter" installation key:

```bash
limacharlie installation-key list --oid <SELECTED_ORG_ID> --output yaml
```

Look for a key with description 'Test Adapter' and extract its `iid`.

**If "Test Adapter" key exists**: Extract the `iid` value from the response.

**If not exists**: Create one:

```bash
limacharlie installation-key create --oid <SELECTED_ORG_ID> --output yaml
```

Save the returned `iid` for later phases.

> **IMPORTANT**: For adapters, the `installation_key` parameter is the **IID (UUID format)**, NOT the full base64-encoded key used by EDR sensors.

### Phase 2: Sample Collection & Parsing Configuration (MANDATORY)

> **DO NOT SKIP THIS PHASE.** You MUST use the `parsing-helper` skill to generate parsing configuration. Never write Grok patterns manually - the parsing-helper will identify timezone requirements and other critical settings.

Before deploying the adapter, capture sample logs and configure parsing rules. This ensures your logs are properly parsed when they arrive in LimaCharlie.

**Step 1**: Copy the helper script to `/tmp`:

```bash
cp plugins/lc-essentials/skills/test-limacharlie-adapter/lc-adapter-helper.sh /tmp/ && chmod +x /tmp/lc-adapter-helper.sh
```

**Step 2**: Capture sample logs to a file:

```bash
/tmp/lc-adapter-helper.sh sample 20 > /tmp/lc-adapter-samples.txt
cat /tmp/lc-adapter-samples.txt
```

**Step 3**: Read the sample file content using the Read tool to have it in context.

**Step 4**: Invoke the parsing-helper skill:

```
Skill("parsing-helper")
```

When parsing-helper asks for sample logs, provide the captured samples from `/tmp/lc-adapter-samples.txt` that are already in context. Inform parsing-helper this is for a **One-off/USP Adapter** (local adapter).

The parsing-helper will:
- Analyze the sample logs
- Generate appropriate Grok pattern
- Test the pattern with `validate_usp_mapping`
- Provide CLI config format for the mapping

**Step 5**: Extract the mapping parameters from parsing-helper output.

The parsing-helper will output mapping parameters like:
- `--grok '<PATTERN>'`
- `--event-type '<PATH>'`
- `--event-time '<PATH>'`
- `--event-time-tz '<TIMEZONE>'` (when timestamp format lacks timezone info)
- `--hostname-path '<PATH>'`

Save these for use in the adapter setup (Phase 3).

### Phase 3: Setup and Start the Adapter (Using Helper Script)

The helper script (already copied in Phase 2) handles platform detection, downloading, and running the adapter.

**Step 1**: Run setup with OID, IID, and mapping config from Phase 2:

```bash
/tmp/lc-adapter-helper.sh setup <OID> <IID> \
  --grok '<GROK_PATTERN_FROM_PARSING_HELPER>' \
  --event-type '<EVENT_TYPE_PATH>' \
  --event-time '<EVENT_TIME_PATH>' \
  --event-time-tz '<TIMEZONE>' \
  --hostname-path '<HOSTNAME_PATH>'
```

> **Note**: Include `--event-time-tz` when the parsing-helper indicates it's needed (e.g., for SYSLOGTIMESTAMP which lacks timezone info).

This command automatically:
- Detects your platform (Linux/Mac, architecture)
- Detects log source (journalctl, log files, or unified logging)
- Creates a temp directory
- Downloads the correct adapter binary
- Creates the launch script with parsing configuration
- Saves configuration for later commands

**Step 2**: Start the adapter:

```bash
/tmp/lc-adapter-helper.sh start
```

### Helper Script Commands Reference

| Command | Description |
|---------|-------------|
| `sample [count]` | Capture sample logs (default 20 lines) |
| `setup <oid> <iid> [--grok ...] [--event-type ...] [--event-time ...] [--event-time-tz ...] [--hostname-path ...]` | Download adapter and create launch script with parsing config |
| `start` | Start the adapter in background |
| `stop` | Stop adapter and cleanup all files |
| `status` | Check if adapter is running |
| `logs` | Show adapter logs (last 50 lines) |
| `info` | Show current configuration |

### Manual Setup (Alternative)

If you prefer not to use the helper script, you can set up manually with separate commands:

1. **Detect platform**: `uname -s` and `uname -m`
2. **Create temp dir**: `mktemp -d /tmp/lc-adapter-test-XXXXXX`
3. **Download adapter**: `curl -sSL "<URL>" -o <TEMP_DIR>/lc_adapter && chmod +x <TEMP_DIR>/lc_adapter`
4. **Create launch script**: Use Write tool to create `<TEMP_DIR>/run_adapter