Skip to main content

Playbooks and Rules

Introduction​

The core logic of the Ansible Service resides in its playbooks and the rule files it manages. This document explains the purpose of the primary playbooks and how threat detection rules are organized.

Standard Playbooks​

Playbooks are located in the playbooks/ directory. The service dynamically generates inventory files and injects extra variables into these playbooks during execution.

1. sensor-setup.yml​

This playbook is used for the initial preparation of a sensor host.

  • Main Tasks:
    • Installs required system packages (Docker, git, curl).
    • Configures host networking.
    • Ensures Docker is running and properly configured.
    • Sets up the Ravenxcope directory structure on the host.

2. sensor-activate.yml​

This playbook deploys and starts the detection engines on an already-setup host.

  • Main Tasks:
    • Pulls the necessary Docker images (Suricata/Snort).
    • Deploys the Sensor Agent container.
    • Configures the packet capture interface.
    • Injects sensor-specific configuration (UUID, Backend URL).

3. sensor-initial-setup.yml​

A combined playbook used for fresh installations that performs both host preparation and initial agent deployment.

Rules Management​

The service maintains a repository of detection rules in the rules-default/ directory.

Rule File Types​

  • Suricata Rules (.rules): Signatures for the Suricata IDS/IPS engine.
  • Snort Rules (.conf / .rules): Configuration and signatures for Snort.
  • Generic Configs: Standardized configuration templates for detection engines.

Deployment Workflow​

  1. Upload: Rules are uploaded via the /api/rules/upload endpoint.
  2. Storage: Files are saved in the rules-default/ folder with metadata.
  3. Distribution: During the sensor-activate process, the backend or ansible service can pull these rules and push them to the sensor hosts.

Execution Logic​

When a playbook is triggered:

  1. Inventory Generation: A temporary .ini file is created containing the target host IP, SSH credentials, and sudo password.
  2. Variable Injection: Extra variables (e.g., sensor_uuid, sensor_interface) are passed using the -e flag.
  3. Execution: The service runs ansible-playbook as a child process.
  4. Capturing Logs: The standard output (STDOUT) and standard error (STDERR) are captured and stored in the execution record.
  5. Cleanup: Temporary inventory files are deleted immediately after the process finishes.