Skip to main content

API Reference

Introduction​

The Ansible Service provides a REST API for the Ravenxcope Backend to trigger playbook executions and manage rule files. All endpoints (except health check) are under the /api prefix.

Health Check​

Get Service Status​

Returns the current health and system time of the service.

  • URL: /health
  • Method: GET
  • Response:
{
  "status": "healthy",
  "service": "ansible-executor",
  "time": "2025-12-19T12:00:00Z"
}

Playbook Execution​

Execute Sensor Setup​

Starts the initial configuration of a sensor host.

  • URL: /api/playbooks/sensor-setup
  • Method: POST
  • Body:
{
  "uuid": "sensor-uuid",
  "interface": "eth0",
  "host_ip": "192.168.1.100",
  "host_user": "ubuntu",
  "host_pass": "password123"
}
  • Response (202 Accepted):
{
  "success": true,
  "message": "Playbook execution started",
  "executionId": "exec-123456789",
  "status": "pending"
}

Execute Sensor Activation​

Deploys and activates a specific playbook (e.g., sensor-activate) on a sensor.

  • URL: /api/playbooks/sensor-activate
  • Method: POST
  • Body:
{
  "playbook": "sensor-activate",
  "host": "192.168.1.100",
  "port": 22,
  "username": "ubuntu",
  "password": "password123",
  "variables": {
    "uuid": "sensor-uuid",
    "interface": "eth0",
    "backend_url": "http://10.10.10.70:5009"
  }
}

Execution Management​

List All Executions​

Returns a list of all playbook executions in the current session.

  • URL: /api/executions
  • Method: GET
  • Response:
{
  "success": true,
  "executions": [...],
  "total": 5
}

Get Execution Status​

Returns detailed information about a specific execution, including the full Ansible output.

  • URL: /api/executions/:id
  • Method: GET
  • Response:
{
  "id": "exec-123456789",
  "uuid": "sensor-uuid",
  "status": "completed",
  "output": "...",
  "startedAt": "2025-12-19T12:00:00Z",
  "endedAt": "2025-12-19T12:05:00Z"
}

Rules Management​

Upload Rule File​

Uploads a new rule file to the central repository.

  • URL: /api/rules/upload
  • Method: POST
  • Form Data:
    • file: The rule file to upload.
    • type: (Optional) Rule type (e.g., suricata).
    • description: (Optional) Description of the rules.

List Rule Files​

Lists all available rule files.

  • URL: /api/rules
  • Method: GET

Download Rule File​

Downloads a specific rule file.

  • URL: /api/rules/:filename
  • Method: GET

Delete Rule File​

Removes a rule file from the repository.

  • URL: /api/rules/:filename
  • Method: DELETE