fleet-payload-tasking

What this skill does

# Fleet Payload Tasking Skill

Deploy payloads (scripts) or shell commands to all endpoints in an organization using reliable tasking. Handles offline sensors automatically - tasks queue and execute when sensors come online.

---

## 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) |

> **Architecture Note**: This skill focuses on payload preparation and upload. It delegates the reliable tasking workflow (D&R rules, task deployment, response collection) to the `sensor-tasking` skill to avoid duplication.

---

## When to Use

Use this skill when the user needs to:
- **Run commands fleet-wide**: "Run this script on all Linux servers", "Execute a command across all endpoints"
- **Collect data from endpoints**: "Get OS version from all machines", "Collect installed packages"
- **Vulnerability scanning**: "Find all endpoints with log4j", "Check for vulnerable OpenSSL versions"
- **Software inventory**: "What versions of Chrome are installed?", "Find all Java installations"
- **Compliance checks**: "Verify security configurations across the fleet"
- **Custom data collection**: "Run this custom script and collect results"

## Two Deployment Approaches

### Approach 1: Shell Commands (Simple, Quick)

For simple data collection, use `run --shell-command` directly - no payload upload needed:

```bash
limacharlie task reliable-send --task 'run --shell-command hostname' --selector 'plat == macos' --context shell-scan-001 --ttl 3600 --oid <oid> --output yaml
```

**Pros:**
- No payload upload step
- Direct command execution
- Simpler workflow

**Cons:**
- Command line length limits
- Escaping becomes painful for complex scripts with quotes/JSON
- Less reusable

### Approach 2: Payload Scripts (Complex, Reusable)

For complex operations, upload a payload script first:

1. Create and upload payload
2. Create D&R rule to collect results
3. Deploy via reliable tasking
4. Collect artifacts

**Pros:**
- Handles complex logic
- Reusable across scans
- Can write large result files

**Cons:**
- More setup steps
- Requires payload management

## Architecture Overview

```
┌─────────────────────────────────────────────────────────────────────────┐
│                      FLEET PAYLOAD TASKING                               │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  OPTION A: Shell Command (Simple)                                       │
│  ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐     │
│  │ Build           │───▶│ Deploy via      │───▶│ D&R rule        │     │
│  │ run --shell-cmd │    │ reliable_tasking│    │ captures STDOUT │     │
│  │ command         │    │                 │    │ as detection    │     │
│  └─────────────────┘    └─────────────────┘    └─────────────────┘     │
│                                                                         │
│  OPTION B: Payload Script (Complex)                                     │
│  ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐     │
│  │ Generate & Upload│───▶│ Create D&R rule │───▶│ Deploy via      │     │
│  │ payload script  │    │ to file_get     │    │ reliable_tasking│     │
│  │                 │    │ result file     │    │                 │     │
│  └─────────────────┘    └─────────────────┘    └─────────────────┘     │
│                                    │                                    │
│                                    ▼                                    │
│                          ┌─────────────────┐                            │
│                          │ Results stored  │                            │
│                          │ as artifacts    │                            │
│                          └─────────────────┘                            │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘
```

## Key Benefits

| Feature | Benefit |
|---------|---------|
| **Reliable Tasking** | Handles offline sensors - task executes when they come online |
| **Flexible Targeting** | Use sensor selectors (tags, platform, hostname patterns) |
| **Shell or Payload** | Choose simple commands or complex scripts |
| **Async Workflow** | Deploy now, collect results later |
| **Cross-Platform** | Linux, macOS, Windows support |
| **Scalable** | Works across thousands of endpoints |

## Platform Requirements

> **WARNING**: Only **EDR agents** support tasking (not adapters or cloud sensors).
>
> **Taskable sensors require BOTH:**
> - **Platform**: `windows`, `linux`, `macos`, or `chrome`
> - **Architecture**: NOT `usp_adapter` (code 9)
>
> A sensor running on Linux but with `arch=usp_adapter` is an **adapter** (USP), not an EDR.
> Cloud sensors, adapters, and USP log sources will fail with `UNSUPPORTED_FOR_PLATFORM`.

When using sensor selectors, always filter by **both platform AND architecture**:
- `(plat == windows or plat == linux or plat == macos) and arch != usp_adapter`

## Shell Command Escaping Considerations

When using `run --shell-command`, the command string is passed through multiple layers:
1. JSON encoding (in the reliable tasking API call)
2. Shell parsing on the endpoint

**Simple commands work well:**
```bash
run --shell-command whoami
run --shell-command 'ls -la /tmp'
run --shell-command "cat /etc/hostname"
```

**Complex operations become difficult:**
- Nested quotes: `echo '{"key":"value"}'` requires careful escaping
- Variable expansion: `$(command)` needs consideration
- Multiple commands: `cmd1 && cmd2 || cmd3` with complex logic
- JSON generation inline becomes messy quickly

**Rule of thumb:** If your command needs more than 2-3 simple pipes or redirects, or involves JSON/complex quoting, use a payload script instead.

## Shell Command Workflow (Recommended for Simple Tasks)

### Step 1: Select Organization

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

### Step 2: Build Shell Command

Keep shell commands **simple** to avoid escaping nightmares:

```bash
# Example: Get hostname from endpoints
run --shell-command 'hostname'

# Example: Check for specific file
run --shell-command 'test -f /var/log/auth.log && echo "found" || echo "not found"'

# Example: Get OS information
run --shell-command 'uname -a'
```

> **WARNING**: For scripts with complex quoting, loops, JSON generation, or multiple commands, use the **Payload Script Workflow** instead to avoid escaping issues.

### Step 3: Deploy and Collect Results (Delegate to sensor-tasking)

> **IMPORTANT**: The `sensor-tasking` skill handles the complete deployment workflow:
> - Creates D&R rule for response collection (BEFORE task deployment)
> - Deploys via reliable tasking
> - Collects and formats results

Use the `sensor-tasking` skill with your prepared shell command:

```
Skill(lc-essentials:sensor-tasking)

Provide to sensor-tasking:
- Task command: run --shell-command 'hostname'
- Selector: plat == macos (or your target selector)
- Context: hostname-scan-001 (for response collection)
- TTL: 3600 (or desired expiratio