fleet-payload-tasking

name	fleet-payload-tasking
description	Deploy payloads and shell commands fleet-wide using reliable tasking. Execute scripts, collect data, or run commands across all endpoints with automatic handling of offline sensors. Use for vulnerability scanning, data collection, software inventory, compliance checks, or any fleet-wide operation.
allowed-tools	["Task","Read","Bash","Write","Skill","AskUserQuestion"]

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

Rule	Wrong	Right
MCP Access	Call mcp__* directly	Use limacharlie-api-executor sub-agent
LCQL Queries	Write query syntax manually	Use generate_lcql_query() first
Timestamps	Calculate epoch values	Use date +%s or date -d '7 days ago' +%s
OID	Use org name	Use UUID (call list_user_orgs 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:

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

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:

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

Selector	Example	Description
All sensors	*	Every sensor in org
By platform	plat == windows	Only Windows sensors
By tag	"production" in tags	Sensors with specific tag
Combined	plat == linux and "webserver" in tags	Multiple criteria
By hostname	hostname == "server1.example.com"	Specific host

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

Issue	Cause	Resolution
No results	Sensors offline	Wait for TTL period
Partial results	Some sensors offline	Check list_reliable_tasks for pending
D&R not matching	Wrong STDOUT pattern	Verify regex matches actual output
Payload failed	Script error	Check RECEIPT events for STDERR

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