Skip to main content

Overview

Introduction​

The Ravenxcope Ansible Service is a central orchestration component that handles the configuration and activation of remote sensor hosts. Built with Go and the Gin framework, it acts as an API-driven wrapper around Ansible, allowing the Ravenxcope Backend to trigger complex system configurations through simple HTTP requests.

The service is responsible for:

  1. Playbook Execution — Running standardized Ansible playbooks for sensor setup and activation.
  2. Rule Management — Storing and serving threat detection rule files (e.g., Suricata, Snort) to be deployed on sensors.
  3. Execution Tracking — Maintaining a log of playbook runs, including status, start/end times, and full CLI output.

Role in the Architecture​

Defense CenterFrontendBackendAnsible ServiceRemote SensorsSensor ASensor B...Sensor NHeartbeatsSSH / Playbooks

The Ansible Service is internal to the Defense Center. It receives commands from the Backend and communicates with Remote Sensors via SSH.

Core Capabilities​

1. Sensor Lifecycle Management​

  • Initial Setup — Preparing a fresh host with necessary dependencies (Docker, networking).
  • Activation — Deploying detection engines (Suricata/Snort) and connecting them to the backend.
  • Deactivation — Gracefully removing setups and cleaning up host resources.

2. Threat Detection Rules​

  • Central Repository — Serves as the "source of truth" for rule files.
  • Dynamic Updates — Allows uploading new rules which are then pushed to sensors during activation.

3. Asynchronous Execution​

  • Non-blocking API — Returns an executionId immediately while the playbook runs in the background.
  • Detailed Logs — Captures standard output and error from the ansible-playbook command for debugging.

Technology Stack​

CategoryTechnologyVersionPurpose
RuntimeGo1.21+Service logic and API
API FrameworkGinlatestHTTP routing and middleware
OrchestrationAnsiblelatestRemote host configuration
ContainerDocker—Service deployment

Key Design Principles​

  1. API-First Orchestration — All Ansible operations are exposed as RESTful endpoints.
  2. Dynamic Inventory — Generates temporary Ansible inventory files on-the-fly based on request parameters.
  3. Stateless Operations — Does not require a database; tracks current session executions in memory.
  4. Security — Uses SSH password/key authentication with privilege escalation (become: yes) to manage remote hosts.