# alir3z4/ansible-suricata architecture

> Architecture diagram of the GitHub repository alir3z4/ansible-suricata, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alir3z4/ansible-suricata
- Repository: https://github.com/alir3z4/ansible-suricata

## Overview

##### Project type and purpose
- This is an Ansible “role” (infrastructure-as-code) whose purpose is to deploy and configure the Suricata intrusion detection system on one or more target hosts, fetch and install Snort rule sets via Oinkmaster, and manage configuration files, directories, and service restarts.

##### File structure
- Top-level files:
- README.md – describes usage, variables, and examples.
- LICENSE, .gitignore – licensing and VCS ignore rules.
- Role directories:
- defaults/main.yml – default role variables (sniffing interface, rule URLs, log dirs).
- handlers/main.yml – service-restart logic (e.g., reload or restart Suricata after config changes).
- meta/main.yml – role metadata (author, dependencies).
- tasks/main.yml – ordered list of tasks (install packages, create dirs, download rules, template configs, invoke handlers).
- templates/… – Jinja2 templates for Suricata and Oinkmaster config files; helper scripts for disabling offload and updating rules.

##### Key insights from README
- The role is pulled in as a Git submodule under `roles/`.
- It expects an inventory group (e.g., “nids”) with group_vars for customizing interfaces, URLs, and directories.
- Usage is purely via Ansible playbooks; no external dependencies except Python/Ansible on the control node and SSH access to managed hosts.

##### Diagramming the architecture
a. Main components to represent:
1. Ansible Control Node – holds the role directory structure, inventory, group_vars, and playbook.
2. Inventory / Group Vars – defines target host groups (“nids”) and custom variables.
3. Remote Managed Host(s) – the NIDS hosts where Suricata runs.
4. External Rules Repository – HTTP server providing emerging.rules.tar.gz.
5. Suricata Service – processes packets, writes logs.
6. Oinkmaster Script – fetches and extracts Snort rules to Suricata’s rules dir.
7. Local Log Directory – /var/log/suricata and subdirectories.

b. Relationships and data flows:
- Control Node → Managed Host: SSH/Ansible connections to execute tasks (package installs, file templates, scripts).
- Managed Host → External Rules URL: HTTP GET to download rule archives.
- Templates on Control Node → Rendered configs on Managed Host → trigger handler to restart/reload Suricata.
- Oinkmaster script runs on Managed Host to process rules and drop them into /etc/suricata/rules/.
- Suricata reads its config, applies rules, writes events to /var/log/suricata/.

c. Architectural patterns & principles:
- “Desired State” configuration – declared in YML tasks and defaults.
- Idempotent operations – use Ansible modules (package, get_url, template, service).
- Separation of concerns – distinct roles for defaults, tasks, handlers, templates.
- Single responsibility – each task does one thing (install, download, template, notify).

d. Technologies and frameworks:
- Ansible (YAML playbooks, roles, modules, Jinja2 templates).
- Suricata IDS (daemon, config files, rule engine).
- Oinkmaster (rule downloader/parser).
- SSH for control->managed communication.
- HTTP for external rule archives.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Control Node"
        direction TB
        Playbook["Playbook.yml"]:::control
        Inventory["Inventory (hosts, group_vars)"]:::control
        subgraph "Ansible Role"
            direction TB
            Defaults["defaults/main.yml"]:::control
            Handlers["handlers/main.yml"]:::control
            Meta["meta/main.yml"]:::control
            Tasks["tasks/main.yml"]:::control
            subgraph "templates"
                direction TB
                T1["etc/init/suricata.conf.j2"]:::control
                T2["etc/oinkmaster.conf.j2"]:::control
                T3["etc/suricata/suricata.yaml.j2"]:::control
                T4["etc/suricata/local.rules.j2"]:::control
                T5["opt/disable_network_offload.sh.j2"]:::control
                T6["opt/update_oinkmaster_ruleset.sh.j2"]:::control
            end
        end
        README["README.md"]:::control
        GITIGNORE[".gitignore"]:::control
        LICENSE["LICENSE"]:::control
    end

    subgraph "Managed Host"
        direction TB
        Install["Install packages"]:::managed
        Download["Download rules (get_url)"]:::managed
        TemplateDeploy["Deploy config templates"]:::managed
        HandlerNotify["Handler: restart/reload Suricata"]:::managed
        subgraph "Scripts"
            direction TB
            S1["disable_network_offload.sh"]:::managed
            S2["update_oinkmaster_ruleset.sh"]:::managed
        end
        subgraph "Services"
            direction TB
            Oink["Oinkmaster"]:::managed
            Suricata["Suricata Service"]:::managed
        end
        Logs["/var/log/suricata"]:::managed
    end

    External["Emerging Rules Archive"]:::external

    Playbook --> Tasks
    Inventory --> Tasks
    Tasks -->|"SSH/Ansible"| Install
    Tasks -->|"SSH/Ansible"| Download
    Tasks -->|"SSH/Ansible"| TemplateDeploy
    Download -->|"HTTP GET"| External
    TemplateDeploy -->|"notify"| HandlerNotify
    HandlerNotify -->|"reload"| Suricata
    Download -->|"run"| S2
    S2 -->|"update rules"| Oink
    Oink -->|"drop rules"| Suricata
    Suricata -->|"write logs"| Logs

    click Defaults "https://github.com/alir3z4/ansible-suricata/blob/master/defaults/main.yml"
    click Handlers "https://github.com/alir3z4/ansible-suricata/blob/master/handlers/main.yml"
    click Meta "https://github.com/alir3z4/ansible-suricata/blob/master/meta/main.yml"
    click Tasks "https://github.com/alir3z4/ansible-suricata/blob/master/tasks/main.yml"
    click T1 "https://github.com/alir3z4/ansible-suricata/blob/master/templates/etc/init/suricata.conf.j2"
    click T2 "https://github.com/alir3z4/ansible-suricata/blob/master/templates/etc/oinkmaster.conf.j2"
    click T3 "https://github.com/alir3z4/ansible-suricata/blob/master/templates/etc/suricata/suricata.yaml.j2"
    click T4 "https://github.com/alir3z4/ansible-suricata/blob/master/templates/etc/suricata/local.rules.j2"
    click T5 "https://github.com/alir3z4/ansible-suricata/blob/master/templates/opt/disable_network_offload.sh.j2"
    click T6 "https://github.com/alir3z4/ansible-suricata/blob/master/templates/opt/update_oinkmaster_ruleset.sh.j2"
    click README "https://github.com/alir3z4/ansible-suricata/blob/master/README.md"
    click GITIGNORE "https://github.com/alir3z4/ansible-suricata/blob/master/.gitignore"
    click LICENSE "https://github.com/alir3z4/ansible-suricata/tree/master/LICENSE"

    classDef control fill:#D0E6FF,stroke:#0366d6,color:#000;
    classDef managed fill:#D0FFD8,stroke:#22863a,color:#000;
    classDef external fill:#FFE0B2,stroke:#d15704,color:#000;
```
