# mohamedsaifi0/ids_bash architecture

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

- Interactive diagram: https://gitdiagram.com/mohamedsaifi0/ids_bash
- Repository: https://github.com/mohamedsaifi0/ids_bash

## Overview

##### Project Type and Purpose
- This is a shell‐based Intrusion Detection System (IDS) written entirely in Bash.
- Purpose: continuously monitor system and application logs for suspicious patterns, generate alerts, optionally block malicious IPs, and provide an interactive administration interface.

##### File Structure
- Top‐level “ids.sh”: the orchestration and command‐line interface (start/stop/status/menu).
- “config.sh”: centralized configuration (log paths, alert toggles, block duration, firewall back end).
- “functions/” directory: four modules by responsibility
- monitor.sh – reads and parses log files
- alert.sh – dispatches notifications (email, wall, log)
- firewall.sh – manages UFW/iptables rules for blocking/unblocking
- process.sh – handles lifecycle commands (start, stop, clean, summary)
- Other artifacts (logs/, reports/) are specified in README but may be generated at runtime.

##### Extract Key Architectural Insights from the README
- Three monitoring modes: forked processes, thread simulation, subshells—this implies a multi‐process modular design.
- External dependencies: whiptail (UI), mailutils (email), iptables/UFW (firewall).
- Core workflow: detect → alert → respond (auto‐block/whitelist) → log/report.

##### Main Components
a. Core Orchestrator (ids.sh + process.sh)
b. Configuration Layer (config.sh)
c. Detection Engine (monitor.sh)
d. Alerting Service (alert.sh)
e. Response Service (firewall.sh)
f. Interactive Admin UI (whiptail/dialog via ids.sh menu)
g. Persistent Storage (log files in /var/log/ids, reports/)
h. External Services
- Mail server (SMTP)
- System firewall (iptables/UFW)
- System console (wall)

##### Relationships and Data Flows
- On “start,” Core Orchestrator loads Configuration, spawns Detection Engine in chosen mode.
- Detection Engine tails multiple system logs → when pattern matches → emits an event object to Alerting Service.
- Alerting Service decides on notification channels (email, wall, log file) and writes to Reports storage.
- Response Service listens to events tagged “auto‐block,” consults whitelist/blacklist, then interacts with firewall subsystem.
- Interactive UI calls Core Orchestrator / Process Service to query status, block/unblock IPs, or perform maintenance (clean, summary).
- All modules read from config.sh; errors and statuses propagate back to orchestrator and UI.

##### Architectural Patterns and Design Principles
- Modular decomposition: each security concern (monitor, alert, block, process) is a separate function script.
- Single responsibility and separation of concerns.
- Pluggable concurrency modes: fork, simulated threads, subshell.
- Event‐driven workflow: detection generates events, events fan out to alert & response.
- Configuration‐driven behavior.

##### Detail
- Which logs are watched by the Monitor (auth.log, syslog, etc.).
- Whitelist/blacklist as data store consulted by Firewall module.
- Timing (real‐time monitoring) or maintenance tasks under Process module.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "User Interface"
        UI["Interactive Admin UI\n(whiptail menu)"]:::orchestrator
        click UI "https://github.com/mohamedsaifi0/ids_bash/blob/main/ids.sh"
    end

    %% Core Orchestrator
    Orchestrator["Core Orchestrator\n(ids.sh)\ncommands: start/stop/status"]:::orchestrator
    click Orchestrator "https://github.com/mohamedsaifi0/ids_bash/blob/main/ids.sh"

    UI -->|"invoke commands"| Orchestrator

    %% Modules Layer
    subgraph "Modules"
        Monitor["Monitor Module\n(functions/monitor.sh)\ntails logs, detects patterns\n(concurrency modes)"]:::module
        click Monitor "https://github.com/mohamedsaifi0/ids_bash/blob/main/functions/monitor.sh"
        Alert["Alert Module\n(functions/alert.sh)\nsends email, wall, log"]:::module
        click Alert "https://github.com/mohamedsaifi0/ids_bash/blob/main/functions/alert.sh"
        Firewall["Firewall Module\n(functions/firewall.sh)\nblocks/unblocks IPs"]:::module
        click Firewall "https://github.com/mohamedsaifi0/ids_bash/blob/main/functions/firewall.sh"
        Process["Process Module\n(functions/process.sh)\nstart, stop, clean, summary"]:::module
        click Process "https://github.com/mohamedsaifi0/ids_bash/blob/main/functions/process.sh"
    end

    Orchestrator -->|"spawn monitor"| Monitor
    Orchestrator -->|"maintenance cmds"| Process
    Process -->|"control service"| Orchestrator

    %% Configuration
    Config["Configuration\n(config.sh)"]:::config
    click Config "https://github.com/mohamedsaifi0/ids_bash/blob/main/config.sh"

    Config -.-> Monitor
    Config -.-> Alert
    Config -.-> Firewall
    Config -.-> Process
    Config -.-> Orchestrator

    %% Data Flow
    Logs["Logs\n(/var/log/ids)"]:::storage
    Reports["Reports\n(reports/)"]:::storage

    Logs -->|"tails auth.log, syslog"| Monitor
    Monitor -->|"event object"| Alert
    Alert -->|"write reports"| Reports
    Alert -->|"send email"| Mail
    Alert -->|"send wall"| Console
    Alert -->|"log write"| Logs

    Monitor -->|"auto-block event"| Firewall
    Firewall -->|"apply rules"| FWsub

    %% External Systems
    subgraph "External Services"
        Mail["Mail Server\n(SMTP)"]:::external
        Console["System Console\n(wall)"]:::external
        FWsub["iptables/UFW subsystem"]:::external
    end

    %% Legend
    subgraph "Legend"
        LO["Orchestrator"]:::orchestrator
        LM["Modules"]:::module
        LC["Config"]:::config
        LS["Storage"]:::storage
        LE["External"]:::external
    end

    classDef orchestrator fill:#f9f,stroke:#333,stroke-width:2px;
    classDef module fill:#bbf,stroke:#333,stroke-width:1px;
    classDef config fill:#ffeb3b,stroke:#333,stroke-width:1px;
    classDef storage fill:#9f9,stroke:#333,stroke-width:1px;
    classDef external fill:#fc9,stroke:#333,stroke-width:1px;
```
