Metadata-Version: 2.4
Name: security-shallots
Version: 0.1.0
Summary: Lightweight self-hosted SIEM — runs on a Raspberry Pi, scales to a server
Author: Ben Olenick
License-Expression: MIT
Project-URL: Homepage, https://github.com/benolenick/security-shallots
Project-URL: Repository, https://github.com/benolenick/security-shallots
Project-URL: Issues, https://github.com/benolenick/security-shallots/issues
Keywords: siem,security,monitoring,ids,suricata,network-security
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Networking :: Monitoring
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.9
Requires-Dist: aiosqlite>=0.19
Requires-Dist: pyyaml>=6.0
Requires-Dist: maxminddb>=2.4
Requires-Dist: aiofiles>=23.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# Security Shallots

A lightweight, self-hosted SIEM that runs on anything — from a Raspberry Pi to a full server.

No Splunk. No Elastic. No Docker required. Just Python and SQLite.

```
pip install .
shallot run
```

Open `http://localhost:8844` and you're monitoring.

## What it does

Security Shallots collects security alerts from your network, deduplicates and enriches them, detects attack patterns, and gives you a single dashboard to review everything.

**Sources it can ingest:**
- Suricata IDS (EVE JSON logs)
- Syslog (routers, firewalls, anything that speaks syslog)
- pfSense (firewall logs + DHCP via API)
- Wazuh (HIDS/EDR alerts)
- CrowdSec (behavioral blocks)
- Pi-hole (DNS query logs)
- Argus endpoint agents (Windows EDR)
- Web application logs

**What it does with them:**
- Normalizes alerts into a common format
- Deduplicates repeated noise
- Auto-classifies severity and suppresses known false positives
- Correlates patterns (port scans, brute force, lateral movement)
- Groups related alerts into incidents with response runbooks
- Optional AI triage via API (OpenAI/Anthropic) — no local GPU needed
- Web dashboard with real-time WebSocket feed

## Hardware auto-detection

Shallots detects your hardware on startup and adjusts automatically:

| System | RAM | CPU | What runs |
|--------|-----|-----|-----------|
| Raspberry Pi | 2 GB | 1 core | Suricata + syslog, basic correlations |
| Old laptop | 4 GB | 2 cores | + CrowdSec, incidents, AI via API |
| Desktop | 8 GB | 4 cores | + Wazuh, agents, full analytics |
| Server | 16+ GB | 8+ cores | Full threat engine (baselines, graph, ML, kill chain) |

On a 4 GB machine, Shallots uses **~200-400 MB RAM** with the threat engine disabled.
Storage: 30 days of alerts from a home network uses ~200-500 MB of SQLite.

## Quick start

### 1. Install

```bash
git clone https://github.com/benolenick/security-shallots.git
cd security-shallots
python -m venv .venv
source .venv/bin/activate
pip install .
```

### 2. Configure

```bash
cp config.example.yaml config.yaml
nano config.yaml
```

Key settings:
- `network.home_cidr` — your LAN range (e.g. `192.168.1.0/24`)
- `suricata.eve_path` — path to Suricata's eve.json
- `web.username` / `web.password` — dashboard login (recommended)
- `profile` — `auto` (default), or force `lite` / `micro` / `standard` / `full`

### 3. Run

```bash
# Foreground (for testing)
shallot run

# As a systemd service
sudo cp setup/shallotd.service /etc/systemd/system/
sudo systemctl enable --now shallotd
```

### 4. Dashboard

Open `http://your-ip:8844`.

## Profiles

Set `profile: auto` (the default) and Shallots picks the right mode:

| Profile | RAM | Components | Threat engine |
|---------|-----|------------|---------------|
| **lite** | < 2 GB | Suricata + syslog | Off |
| **micro** | 2-4 GB | + CrowdSec | Off |
| **standard** | 4-8 GB | + Wazuh, VictoriaLogs, Grafana | Tuned down |
| **full** | 8+ GB | Everything including Argus agents | Full |

Override: `profile: lite` in config.yaml.

## AI triage

Works without AI — you can manually review alerts. Add an API key for automatic classification:

```yaml
ai:
  tier: remote_api
  anthropic_api_key: "sk-ant-..."   # or openai_api_key
```

Cost: a few cents per day for a typical home network. No GPU needed.

For local AI (if you have the hardware):

```yaml
ai:
  tier: local
  ollama_url: "http://localhost:11434"
  ollama_model: "qwen3:14b"
```

## pfSense integration

Configure pfSense to send syslog to your Shallots host:
- Status > System Logs > Settings > Remote Logging > add your Shallots IP
- Enable syslog in config.yaml with matching port

Optional API integration pulls DHCP leases for IP-to-hostname mapping.

## CLI

```bash
shallot run                              # Start daemon (foreground)
shallot status                           # Component health + alert stats
shallot query "show SSH attacks today"   # AI natural language query
shallot health                           # Detailed health check
```

## Architecture

```
[Suricata] ──┐
[Syslog]   ──┤
[pfSense]  ──┼──> Queue ──> Pipeline ──> SQLite ──> REST API ──> Dashboard
[Wazuh]    ──┤              (normalize,            (aiohttp)     (vanilla JS)
[CrowdSec] ──┘               dedup,
                              enrich,
                              classify)
                                |
                          Correlator ──> Incidents
                          (port scan,    (grouped alerts
                           brute force,   with runbooks)
                           lateral mvmt)
```

- **Python asyncio** — single process, cooperative multitasking
- **SQLite + FTS5** — full-text search, no external database
- **5 pip dependencies** — aiohttp, aiosqlite, pyyaml, maxminddb, aiofiles
- **Vanilla JS frontend** — no React, no build tools, no node_modules

## Project structure

```
shallots/
  daemon.py          # Main orchestrator — starts all workers
  config.py          # YAML config + hardware auto-detection
  cli.py             # CLI entry point
  ingest/            # Data source ingestors (suricata, syslog, etc.)
  pipeline/          # normalize -> dedup -> enrich -> classify
  ai/                # Triage, correlator, incidents, autopilot
  store/             # SQLite database layer
  web/
    api.py           # REST API endpoints
    app.py           # aiohttp app factory
    static/          # Dashboard (vanilla JS SPA)
```

## Development

```bash
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install -e ".[dev]"
python -m shallots run --debug
```

## License

MIT
