Fleet Payload Tasking

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.

API Access Pattern

All LimaCharlie API calls go through the limacharlie-api-executor sub-agent:

Task(
  subagent_type="lc-essentials:limacharlie-api-executor",
  model="sonnet",
  prompt="Execute LimaCharlie API call:
    - Function: <function-name>
    - Parameters: {<params>}
    - Return: RAW | <extraction instructions>
    - Script path: {skill_base_directory}/../../scripts/analyze-lc-result.sh"
)

Critical Rules

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:

reliable_tasking(
  task="run --shell-command 'hostname'",
  selector="plat == macos",
  context="shell-scan-001",
  ttl=3600
)

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

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:

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

lc_call_tool(
  tool_name="list_user_orgs",
  parameters={}
)

Step 2: Build Shell Command

Keep shell commands simple to avoid escaping nightmares:

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

The sensor-tasking skill will:

1. Create a D&R rule to capture RECEIPT events with your context
2. Deploy the reliable task to matching sensors
3. Collect responses via LCQL query
4. Return aggregated results

See the sensor-tasking skill documentation for:

• D&R rule creation workflow
• Response collection via LCQL
• Monitoring task progress
• Result aggregation patterns

Payload Script Workflow (For Complex Operations)

Step 1: Generate Payload Script

Create a script that:

1. Performs the desired operation
2. Writes JSON results to a temp file
3. Outputs ONLY the file path to STDOUT

Example: Cross-platform mktemp handling

#!/bin/bash
SCAN_ID="$1"

# Cross-platform mktemp (macOS requires different syntax)
if [ "$(uname)" = "Darwin" ]; then
    OUTPUT_FILE=$(mktemp /tmp/lc-fleet-scan.XXXXXX)
    mv "$OUTPUT_FILE" "${OUTPUT_FILE}.json"
    OUTPUT_FILE="${OUTPUT_FILE}.json"
else
    OUTPUT_FILE=$(mktemp /tmp/lc-fleet-scan-XXXXXX.json)
fi

# Write results to file
echo '{"scan_id":"'$SCAN_ID'","hostname":"'$(hostname)'","results":[]}' > "$OUTPUT_FILE"

# CRITICAL: Output ONLY the file path
echo "$OUTPUT_FILE"

Step 2: Upload Payload

Use file_content with base64-encoded script:

# Encode the script
base64 -w0 /tmp/my-payload.sh

lc_call_tool(
  tool_name="create_payload",
  parameters={
    "oid": "[org-id]",
    "name": "my-payload.sh",
    "file_content": "[base64-encoded-content]"
  }
)

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 uploaded payload:

Skill(lc-essentials:sensor-tasking)

Provide to sensor-tasking:
- Task command: run --payload-name my-payload.sh --arguments 'scan-001'
- Selector: plat == linux (or your target selector)
- Context: scan-001 (for response collection)
- TTL: 604800 (1 week, or desired expiration)

The sensor-tasking skill will:

1. Create a D&R rule to capture RECEIPT events and trigger file_get
2. Deploy the reliable task to matching sensors
3. Collect artifacts from sensor responses
4. Return aggregated results

Note: For payload-based collection, you may want a D&R rule that:

• Matches the file path pattern in STDOUT
• Triggers file_get to retrieve the result file
• Stores results as artifacts

See the sensor-tasking skill documentation for advanced D&R rule patterns.

Sensor Selectors

Monitoring Task Progress

lc_call_tool(
  tool_name="list_reliable_tasks",
  parameters={"oid": "[org-id]"}
)

Shows:

• Which sensors have acknowledged/executed
• Which sensors are still pending (offline)
• Task expiration time

Error Handling

Cleanup

Payload Cleanup (This Skill)

If you uploaded a payload, delete it after the operation:

lc_call_tool(
  tool_name="delete_payload",
  parameters={"oid": "[org-id]", "name": "my-payload.sh"}
)

D&R Rule and Task Cleanup (sensor-tasking)

The sensor-tasking skill handles cleanup for:

• D&R rules created for response collection
• Reliable tasks

See the sensor-tasking skill documentation for cleanup workflows.

Security Considerations

• Approval Workflow: Consider requiring user confirmation before fleet-wide operations
• Input Validation: Sanitize parameters to prevent command injection
• Audit Logging: All operations logged in LimaCharlie audit trail
• Least Privilege: Use sensor selectors to limit scope when possible
• Payload Review: Review payload scripts before deployment

Related Skills

• sensor-tasking - REQUIRED for deployment. Handles reliable tasking, D&R rules for response collection, and result retrieval. Use this skill for the execution workflow after preparing your payload/command here.
• sensor-coverage - Fleet inventory and health before tasking
• detection-engineering - Create custom D&R rules for advanced scenarios
• limacharlie-call - Low-level API access for payload management