API: Automation Actions

Ban addresses, stop processes, quarantine files, run scans and lock servers down with an API key.

Overview and required scope

The Automation API lets your own tools take the same actions an operator can: ban or unban an IP, stop a process, quarantine a file, run a scan, lock a server down, restart the agent. Only an organization owner can create a key with this scope.

Required scope: actions:write (reading bans needs servers:read too) Plan: the Security Policy feature must be on your plan

Every action is written to the audit log under the key's name (api-key:<name>) and goes through your command policies exactly like a dashboard action: if a policy requires approval, the call answers 202 with { "pending_approval": true, "approval_id": "..." } and nothing runs until someone approves it. A 202 alone does not mean approval is needed: check for pending_approval / approval_id in the response. Each host's own limits still apply on the host (see Installing the Agent → --limits).

POST /api/automation/ban-ip — ban an IP address

curl -X POST \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "serverId": "4f2a9c1e8b7d6a50", "ip": "185.220.101.45", "reason": "Flagged by our threat feed" }' \
     https://vigilhold.com/api/automation/ban-ip

ip is an IPv4 or IPv6 address or a CIDR range; reason is optional (max 500 characters). Returns { "ok": true, "sent": true, "serverId": "...", "ip": "..." } — sent is false when the agent is offline; the ban is recorded and applied when it reconnects.

POST /api/automation/unban-ip — remove an IP ban

curl -X POST \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "serverId": "4f2a9c1e8b7d6a50", "ip": "185.220.101.45" }' \
     https://vigilhold.com/api/automation/unban-ip

POST /api/automation/kill — stop a process

curl -X POST \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "serverId": "4f2a9c1e8b7d6a50", "pid": 48213, "reason": "Miner started by the web user" }' \
     https://vigilhold.com/api/automation/kill

signal is SIGKILL (default) or SIGTERM; PIDs 0 and 1 are refused. Returns { "ok": true, "sent": true, "simulated": false, "pid": 48213 }. In simulation mode nothing is stopped and simulated is true.

POST /api/automation/quarantine — quarantine a file

curl -X POST \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "serverId": "4f2a9c1e8b7d6a50", "filePath": "/tmp/.x/kworkerd", "reason": "Dropped by the intrusion" }' \
     https://vigilhold.com/api/automation/quarantine

reason is required. The call answers 202 with { "artifactId": 31, "status_url": "/api/automation/quarantine/31" }; poll that URL until status is quarantined, failed or simulated; polling needs servers:read and actions:write. The agent only moves files from places malware uses and refuses system files. Release or delete quarantined files on the Respond page. Needs the EDR response feature on your plan.

POST /api/automation/scan — trigger a security scan

curl -X POST \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "serverId": "4f2a9c1e8b7d6a50", "scanner": "rkhunter" }' \
     https://vigilhold.com/api/automation/scan

scanner is rkhunter (rootkits) or clamav (malware). The scan runs on the host in the background and what it finds arrives as alerts: poll the Alerts API or subscribe a webhook to the alert.* events you want.

POST /api/automation/lockdown — enable or disable lockdown

# Lock down
curl -X POST \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "serverId": "4f2a9c1e8b7d6a50", "active": true }' \
     https://vigilhold.com/api/automation/lockdown

# Lift it
curl -X POST ... -d '{ "serverId": "4f2a9c1e8b7d6a50", "active": false }' ...

If your command policies require approval for lockdown, the call answers 202 and waits for an approver.

GET /api/automation/server/:id/bans — list active IP bans

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://vigilhold.com/api/automation/server/4f2a9c1e8b7d6a50/bans

Returns an array, newest first: { ip, reason, username, ts } — username is who banned it, ts milliseconds since the epoch.

Tips

All Vigilhold docs · Start a 14-day free trial