elastic / elastic/integrations

[Feature Request] Script/Command execution input for Elastic Agent (like Nagios/Nimsoft logmon)

Open
#20,350 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Handlebars
Stars
333
Forks
647
Avg merge
3d 4h
Merged PRs (30d)
209

Description

## Summary

Add a native **script/command execution input** to Elastic Agent that runs a local command on a configurable schedule and ingests the output (stdout) as a log or metric document into Elasticsearch.

## Use Case

Many monitoring scenarios require collecting data that isn't exposed via WMI, perfmon, event logs, or any existing integration:

- **Application state checks** — Is Outlook running? Is VPN connected? What's the active user session?
- **Custom health checks** — Run a PowerShell/bash script that validates application connectivity, checks certificate expiry, or tests a local service
- **Migration from legacy tools** — Customers moving from Nimsoft (logmon probe), Nagios (check_command), or Zabbix (UserParameter) need an equivalent in Elastic Agent

Currently, the only workaround is:
1. Create an external Scheduled Task
2. Have the script write to Windows Event Log
3. Collect the event via Elastic Agent

This breaks the **single-pane-of-glass** management model of Fleet — you can't centrally deploy, update, or monitor these checks from Kibana.

## Proposed Configuration

```yaml
- command: "powershell.exe -File C:\\Scripts\\check-status.ps1"
args: ["-Param1", "value1"]
period: 60s
timeout: 30s
output_format: json # json | csv | kv | line | plain
working_directory: "C:\\Scripts"
dataset: "custom_script"

# Scheduling options
schedule:
type: cron # interval | cron | trigger
expression: "*/5 8-18 * * 1-5" # Run every 5 min, Sun-Fri 08:00-18:00

# Trigger-based execution (alternative to periodic)
triggers:
- on_agent_start: true # Run when agent starts/restarts
- on_user_login: true # Run when a user logs in (Windows session event)
- on_network_change: true # Run when network adapter state changes

# Execution context
run_as:
user: "DOMAIN\\svc_monitor" # Run as specific user (optional)
password_secret: "exec_svc_password" # Reference to Fleet secret store

# Error handling
retry:
max_attempts: 3
delay: 10s
on_failure: "log" # log | alert | skip

# Output control
only_if_changed: false # Only send event if output differs from last run
environment: # Environment variables passed to the script
ELASTIC_ENV: "production"
CHECK_MODE: "full"
```

### Behavior

| Aspect | Description |
|--------|-------------|
| Execution | Agent spawns the command based on schedule (interval, cron, or trigger) |
| Scheduling | `interval` = every X seconds, `cron` = cron expression with time windows, `trigger` = on events (agent start, user login, network change) |
| Run As | By default runs as Agent service account. Optionally impersonate a specific user (credentials stored in Fleet secrets) |
| Output parsing | See supported formats below |
| Timeout | Kill process after `timeout`, report error |
| Exit code | Non-zero → `event.outcome: failure` |
| Retry | Configurable retry on failure with delay |
| Deduplication | `only_if_changed: true` → skip sending if output identical to previous run |
| Environment | Custom env vars can be injected from Fleet policy |
| Security | Fleet policy controls which commands are allowed; credentials stored in secure vault |

### Supported Output Formats

| Format | Description | Example |
|--------|-------------|---------|
| `json` | Parse stdout as JSON object → document fields | `{"status": "ok", "latency_ms": 42}` |
| `csv` | First line = headers, following lines = values. Each line = one event | `host,status,latency\nsvr1,ok,12` |
| `kv` | Key=value pairs (one per line) | `status=ok\nlatency_ms=42` |
| `line` | Each line of stdout = separate event with `message` field | Any multi-line output |
| `plain` | Entire stdout as single `message` field (no parsing) | Free-form text |

### Example Outputs

**JSON:**
```json
{"outlook": "running", "vpn_status": "connected", "exchange_latency_ms": 45}
```

**CSV:**
```
process,status,pid
OUTLOOK,running,12456
Teams,running,8832
```

**Line (one event per line):**
```
OUTLOOK: running (PID 12456)
Teams: running (PID 8832)
VPN: disconnected
```

## Prior Art

| Tool | Feature | How it works |
|------|---------|--------------|
| **Telegraf** | `inputs.exec` | Runs command, parses JSON/CSV/influx output |
| **Nagios/Icinga** | `check_command` | Runs plugin, parses stdout + exit code |
| **Nimsoft/UIM** | `logmon` probe | Runs script, pattern-matches output |
| **Zabbix** | `UserParameter` | Runs local command, returns value |
| **Metricbeat** | Community `exec` module | Never made it to official (gap remains) |

## Why This Matters

Elastic Agent already supports WMI, perfmon, and event logs — but these cover only **structured Windows APIs**. For anything custom (application-specific checks, multi-step validations, data not exposed by any API), there's no native solution.

This is a **common request** from enterprise customers migrating from traditional monitoring tools to Elastic Observability. Without it, they must maintain parallel scheduling infrastructure (GPO/SCCM/Scheduled Tasks), which defeats the purpose of centralized Fleet management.

## Acceptance Criteria

- [ ] New input type `exec` (or `script`) in Elastic Agent
- [ ] Configurable via Fleet policy (no local config files needed)
- [ ] Supports `period`, `timeout`, `command`, `args`, `working_directory`
- [ ] **Scheduling**: interval, cron expression (with time-of-day/day-of-week support), and event triggers
- [ ] **Triggers**: on agent start, on user login, on network state change
- [ ] **Run As**: execute as a specified user with credentials stored in Fleet secrets
- [ ] Parses stdout into document fields (supports JSON, CSV, key=value, line-per-event, and plain text)
- [ ] Reports exit code and stderr as event metadata
- [ ] Retry on failure with configurable attempts and delay
- [ ] `only_if_changed` option to reduce noise (deduplication)
- [ ] Custom environment variables injectable from policy
- [ ] Works on Windows (PowerShell/cmd) and Linux (bash)
- [ ] Security: allowlist of permitted commands configurable in policy; credentials in secure vault

Contributor guide

Open the contributing guide

Research direction

No files, tests, or entry points are identified. Start by locating the existing WMI, perfmon, and event-log inputs and their Fleet policy schemas, then compare their scheduling, parsing, failure reporting, and credential handling. Done would require an agreed scope and implementation plan covering the listed execution, scheduling, output, security, and platform requirements.

Written by the indexing model from the issue text.

Assessment

Tech stack
bash, powershell
Domain
devops, observability-sre, security
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.