GuardianNode

Local-first personal security and threat intelligence hub for real-time alerts and digital perimeter protection.

Comment

GuardianNode

Local-first physical threat monitoring. No cloud. No middlemen. Your data stays on your machine.

GuardianNode monitors Telegram channels in real time, scores incoming messages against a multilingual threat keyword library, and sends private alerts through your own Telegram bot when the risk score crosses your threshold.

How It Works

Telegram channels (Arabic/EN/RU/HE/…)
      │
      ▼
 TelegramMonitor (Telethon — real-time socket)
      │
      ▼
  Arabic normalizer  ──  strips diacritics, alef variants, tatweel
      │
      ▼
  Risk Scorer  ←── keyword weights × source reliability
      │
      ├── score < threshold  →  silent log (SQLite)
      │
      └── score ≥ threshold  →  Bot API alert → your private Telegram


Personal Vault (AES-256-GCM encrypted at ~/.guardiannode/vault.enc)
      │
      ├── Passwords  →  HIBP k-anonymity (SHA-1 prefix only sent, no Tor needed)
      │
      └── Emails  →  HIBP via Tor  (your IP is never seen by HIBP)
                         ▲
                 new Tor circuit per identity  (stream isolation)

Risk score = keyword_base_score × source_reliability_multiplier

Keyword level Base score Official source Trusted source General source
Critical 90 90 72 45
High 70 70 56 35
Medium 45 45 36 22.5

Requirements

Arabic Language Support

Most channel messages are in Arabic. GuardianNode normalizes Arabic text before matching so keywords work regardless of diacritics, alef variants, or attached prefixes:

Raw in channel After normalize() Keyword match
الإخلاءُ العاجل الاخلاء العاجل اخلاء ✓
وإخلاء المنطقة واخلاء المنطقه اخلاء ✓
تَحْذِيرٌ عاجل تحذير عاجل تحذير ✓
غاراتٌ جوية غارات جويه غارات ✓

Normalization handles: tashkeel removal, أإآ→ا, ة→ه, ى→ي, tatweel removal.

Quick Start

# 1. Clone
git clone https://github.com/ferasbusiness666/guardiannode
cd guardiannode

# 2. Install dependencies
pip install -r requirements.txt

# 3. First-time setup (interactive wizard)
python run.py --setup

# 4. Start monitoring
python run.py

The setup wizard will:

  1. Ask you to set a master password (encrypts all stored credentials)
  2. Collect your Telegram API credentials
  3. Walk you through creating and linking your notification bot
  4. Let you add channels to monitor with reliability ratings
  5. Authenticate once and save an encrypted session

On every subsequent start you are prompted for your master password. Nothing is stored in plaintext.

Where Data Lives

File Purpose
~/.guardiannode/config.enc AES-256-GCM encrypted config (API keys, session)
~/.guardiannode/events.db Local SQLite log of all scored events

The .guardiannode/ directory is created with chmod 700. Config file is chmod 600. Neither file contains plaintext credentials.

Security Design

Concern Mitigation
Credential storage AES-256-GCM encryption; key derived via PBKDF2-SHA256 (600k iterations)
Master password Never written to disk — entered at startup, held in memory only
Telegram session Stored as an encrypted string inside config.enc (Telethon StringSession)
Notification privacy Alerts go to your own bot — no GuardianNode server sees them
Deduplication SHA-256 hash of (channel_id, message_id) prevents duplicate alerts

Configuration

See config.example.yaml for all options.

Key settings:

monitoring:
  alert_threshold: 60   # 0-100. Raise to reduce noise; lower for maximum sensitivity.

  channels:
    - username: "channel_name"
      name: "Display Name"
      reliability_label: official   # official / trusted / general

Custom keywords can be added on top of the built-in multilingual set:

keywords:
  critical:
    - "nuclear alert"
    - "تحذير نووي"

Alert Format

🚨 CRITICAL ALERT
━━━━━━━━━━━━━━━━━━━━
Source: Civil Defense
Risk Score: 90/100
Triggers: `evacuation`, `immediate`
Time: 2025-01-15 14:32:11 UTC
━━━━━━━━━━━━━━━━━━━━
[original message text, up to 500 chars]
━━━━━━━━━━━━━━━━━━━━
⚡ Take immediate protective action. Move to shelter NOW.

Digital Perimeter — Personal Vault

Store your personal identifiers encrypted on-device and scan for breaches:

python run.py --vault     # Add emails, passwords, usernames, keywords
python run.py --scan      # One-shot scan right now
python run.py             # Includes automatic scan every 6 hours

How it stays secure:

Identifier Check method What leaves your device IP visible to HIBP?
Password HIBP k-anonymity First 5 chars of SHA-1 hash only No (clearnet is safe here)
Email HIBP via Tor Your email address No — hidden by Tor

Tor circuit isolation: Each identity in your vault gets its own Tor circuit via SOCKS5 stream isolation. Searching for two emails cannot be correlated by a network observer.

"Reverse hacking" protection:

  • aiohttp makes HTTP requests — no browser, no JavaScript execution, no fingerprinting
  • HTTPS certificate verification is enforced even over Tor
  • No request logs, no query caching — each scan is a clean session
  • If Tor is not running, email checks are silently skipped (password k-anon checks still work)

Tor setup (one-time):

# Linux / Raspberry Pi
sudo apt install tor && sudo systemctl start tor

# macOS
brew install tor && brew services start tor

# Windows: download Tor Browser or Expert Bundle from torproject.org

Project Structure

guardiannode/
├── run.py                  Entry point
├── requirements.txt
├── config.example.yaml     Config reference
├── guardian/
│   ├── crypto.py           AES-256-GCM + PBKDF2 key derivation
│   ├── config.py           Encrypted config load/save
│   ├── keywords.py         Multilingual keyword sets (EN/AR/RU/UK/HE)
│   ├── scorer.py           Risk scoring engine
│   ├── storage.py          SQLite event log + deduplication
│   ├── notifier.py         Telegram Bot API alert sender
│   ├── monitor.py          Telethon real-time channel monitor
│   ├── setup_wizard.py     Interactive first-time setup
│   └── main.py             Async service loop
└── docs/
    ├── ARCHITECTURE.md
    ├── THREAT_INTEL.md
    ├── TELEGRAM_INTEGRATION.md
    ├── DIGITAL_PERIMETER.md
    └── ROADMAP.md

Roadmap

Phase 1 (current): Real-time Telegram monitoring, keyword scoring, encrypted config, local event log.

Phase 2: Local LLM integration (Ollama) for message summarisation, geoparsing to calculate distance from safe zones.

Phase 3: Dark web monitoring (HIBP k-anonymity, Tor-based scrapers), network intrusion detection.

Phase 4: Offline resilience (SDR radio, LoRa), P2P trusted-node alert sharing, acoustic siren detection.

Architecture & Design Docs

See the /docs directory for the full system design, threat intelligence strategy, and digital perimeter specification.

Built With

Share this project:

Updates