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
- Use the Automation API in your SIEM or SOAR playbooks to automatically ban IPs when a threat feed flags them.
- Actions follow your command policies — if one requires approval, the call returns 202 and the action waits for an approver.
- Use GET /api/automation/server/:id/bans in dashboards or status tools to show active IP blocks at a glance.