🛡️ SecPulse

SecPulse is a self-hosted AI-powered security intelligence pipeline that automatically fetches, ranks, deduplicates, and summarises the top 15 cybersecurity stories from 12 curated RSS feeds — delivered daily to your Telegram at a scheduled time.

Built by an MSc Cybersecurity student. Runs 24/7 on a VPS with zero manual effort.

---

📸 Sample Output

🛡 SecPulse Daily Briefing
📅 Tuesday, 21 April 2026
──────────────────────────────

1. SGLang CVE-2026-5760 (CVSS 9.8) Enables RCE via Malicious GGUF Model Files
   A critical CVSS 9.8 vulnerability in SGLang allows remote code execution...
   🔗 Read more → https://thehackernews.com/...

...

⚡ 15 stories · SecPulse · via Gemini

---

✨ Features

• 📡 Fetches from 12 curated security RSS feeds (CISA, BleepingComputer, The Hacker News, NCSC, Dark Reading, and more)
• 🧠 AI summarisation via Google Gemini (with Groq as automatic fallback)
• 🗂️ Category-aware ranking — 3 articles each across Vulnerabilities, Advisories, Breaches, Tools, General
• 🔁 Smart deduplication — never sends the same story twice
• 🚫 Promo filtering — automatically skips webinars, sponsored posts, product showcases
• 📬 Telegram delivery with automatic message chunking for long digests
• 🗄️ SQLite persistence — tracks sent articles across days
• 🐳 Fully Dockerised — one command to run, restart-safe

---

🗂️ Project Structure

.
├── app/
│   ├── config.py          # Loads env vars and config
│   ├── db.py              # SQLite database functions
│   ├── Dockerfile         # Container definition
│   ├── main.py            # Entry point, scheduler
│   ├── models.py          # Article data model
│   ├── ranker.py          # Scoring, categorisation, deduplication
│   ├── requirements.txt   # Python dependencies
│   ├── rss_reader.py      # RSS fetch and parse
│   ├── sender.py          # Telegram delivery
│   └── summariser.py      # Gemini / Groq AI summarisation
├── data/
│   └── secpulse.db        # SQLite DB (auto-created, gitignored)
├── .env                   # Your secrets (gitignored)
├── .env.example           # Template — copy this to .env
├── .gitignore
├── docker-compose.yml
└── README.md

---

⚙️ Prerequisites

Before you start, you need:

Requirement	Free?	Where to get it
Telegram Bot Token	✅ Free	@BotFather on Telegram
Telegram Chat ID	✅ Free	@userinfobot on Telegram
Google Gemini API Key	✅ Free tier available	aistudio.google.com
Groq API Key (fallback)	✅ Free	console.groq.com
Docker + Docker Compose	✅ Free	docs.docker.com
A machine to run it 24/7	See below	—

🤖 AI API Keys — Free vs Paid

SecPulse uses Google Gemini as the primary summariser with Groq as automatic fallback:

• Gemini free tier works for testing but has strict rate limits (15 RPM, 1M tokens/day). For daily scheduled use it's usually fine, but heavy manual testing may hit limits.
• Gemini paid ($0.10–$0.40 per million tokens) costs roughly £3–8/month for daily digests and is the recommended option for reliable production use. Get a key at aistudio.google.com.
• Groq free tier (backup) is used automatically if Gemini fails. Get a key at console.groq.com. No charge needed.

---

🖥️ Where to Run It (24/7 Options)

SecPulse needs to run continuously to deliver scheduled digests. Choose one:

Option	Cost	Effort	Notes
VPS — Hostinger, Hetzner, DigitalOcean	~£3–5/month	Low	Recommended. The author uses Hostinger KVM 2. SSH in, clone, done.
Raspberry Pi	One-time ~£35–50	Medium	Runs great on Pi 4/5. Needs Linux + Docker installed. Always-on at home.
Always-on PC/laptop	Electricity cost	Low	Works, but not ideal — machine must never sleep or shut down.
Oracle Cloud Free Tier	✅ Free forever	Medium	ARM VM (4 CPU / 24 GB RAM). Requires account + card for verification. cloud.oracle.com
Google Cloud / AWS Free Tier	✅ Free (12 months)	Medium	t2.micro / e2-micro. Time-limited free tier.

The author runs SecPulse on a Hostinger KVM 2 VPS (Ubuntu 22.04, 2 vCPU, 8 GB RAM) which costs ~£4.99/month and handles Docker with no issues.

---

🚀 Setup Guide

Step 1 — Clone the Repository

git clone https://github.com/your-username/secpulse.git
cd secpulse

Step 2 — Create Your .env File

cp .env.example .env
nano .env

Fill in your values:

# Telegram
TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_CHAT_ID=your_chat_id_here

# AI — Primary (Google Gemini)
GEMINI_API_KEY=your_gemini_api_key_here

# AI — Fallback (Groq)
GROQ_API_KEY=your_groq_api_key_here

# Digest schedule (24h format, UTC or Europe/London)
DIGEST_CRON_HOUR=9
DIGEST_CRON_MINUTE=0

Tip: To get your Telegram Chat ID, start a chat with @userinfobot and it will reply with your ID.

Step 3 — Install Docker

If Docker isn't installed yet:

# Ubuntu / Debian
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker

# Verify
docker --version
docker compose version

Step 4 — Build and Run

cd secpulse
sudo docker compose up -d --build

Check it started correctly:

sudo docker compose logs -f

You should see:

🛡 SecPulse starting up...
DB initialised OK
  ✅ Scheduler started — next digest at Wednesday 22 Apr 2026 at 09:00 BST
  💡 Run manually anytime: python3 main.py --now
  Press Ctrl+C to stop

Step 5 — Test It Immediately

Run a manual digest right now to confirm everything works end-to-end:

sudo docker compose exec secpulse python3 main.py --now

You should receive a Telegram message within ~30 seconds.

---

🔧 Day-to-Day Commands

# View live logs
sudo docker compose logs -f

# Run a manual digest (uses unsent articles, same as scheduled)
sudo docker compose exec secpulse python3 main.py --now

# Force re-send even if articles already sent (useful for testing)
sudo docker compose exec secpulse python3 main.py --now --force

# Restart the container (e.g. after editing a .py file)
sudo docker compose restart secpulse

# Stop completely
sudo docker compose down

# Rebuild after changing Dockerfile or requirements.txt
sudo docker compose build --no-cache
sudo docker compose up -d

Note: For .py file changes (like main.py, ranker.py), you only need docker compose restart secpulse — no rebuild required, since the app folder is volume-mounted.

---

✏️ Customisation

Change the Digest Schedule

Edit .env:

DIGEST_CRON_HOUR=8    # 8am
DIGEST_CRON_MINUTE=30 # 8:30am

Then restart: sudo docker compose restart secpulse

Add or Remove RSS Feeds

Edit app/rss_reader.py — find the RSS_SOURCES list and add/remove entries:

RSS_SOURCES = [
    {"name": "The Hacker News", "url": "https://feeds.feedburner.com/TheHackersNews"},
    {"name": "Your Feed",       "url": "https://example.com/feed.xml"},
    # ...
]

Change Number of Stories Per Day

Edit app/main.py:

DIGEST_SIZE = 15  # Change to any number

And update the per-category caps in app/ranker.py:

CATEGORY_CAPS = {
    "vulnerability": 3,
    "advisory":      3,
    "breach":        3,
    "tool":          3,
    "general":       3,
}

---

🗄️ Database

SecPulse stores all articles in a SQLite database at ./data/secpulse.db (outside the container, persisted via volume mount).

Useful queries:

# Check sent status of recent articles
sudo docker compose exec secpulse python3 -c "
import sqlite3
conn = sqlite3.connect('/data/secpulse.db')
rows = conn.execute('SELECT sent, COUNT(*) FROM articles GROUP BY sent').fetchall()
for r in rows: print('sent=' + str(r[0]), '->', r[1], 'articles')
"

# View latest 10 articles
sudo docker compose exec secpulse python3 -c "
import sqlite3
conn = sqlite3.connect('/data/secpulse.db')
rows = conn.execute('SELECT title, category, score, sent FROM articles ORDER BY created_at DESC LIMIT 10').fetchall()
for r in rows: print(r)
"

Articles older than 30 days are automatically purged on each run.

---

🐛 Troubleshooting

Problem	Likely Cause	Fix
No Telegram message received	Wrong bot token or chat ID	Check .env values. Test token with curl https://api.telegram.org/bot<TOKEN>/getMe
DB initialised OK but no digest	No unsent articles in DB	Run with --force flag to override
Gemini API error	Rate limit or invalid key	Check key at aistudio.google.com. Groq fallback should kick in automatically.
cannot open database file	Wrong DB path	Confirm ./data/ folder exists: ls -la ~/secpulse/data/
Fewer than 15 stories	Ran manually before scheduled run	Normal — manual runs consume unsent articles. Use --force for testing.
Container keeps restarting	App crash on startup	Check logs: sudo docker compose logs --tail=50

---

📦 Tech Stack

• Python 3.11
• feedparser — RSS parsing
• APScheduler — cron-based scheduling
• Google Gemini API — AI summarisation (primary)
• Groq API — AI summarisation (fallback)
• python-telegram-bot — Telegram delivery
• SQLite — article persistence
• Docker + Docker Compose — containerised deployment

---

🙌 Contributing

PRs and issues welcome. Some ideas for extensions:

• Web dashboard to browse past digests
• Slack / Discord / email delivery alongside Telegram
• Custom keyword alerting (get pinged instantly for specific CVEs)
• CVSS score enrichment via NVD API
• Weekly summary mode in addition to daily