Security Scan Automator

An automated security reconnaissance pipeline that runs scheduled nmap scans, analyzes the output with Claude for a plain-English risk summary, and delivers the report to Telegram.

Built as a portfolio project to demonstrate end-to-end automation: cron scheduling, network reconnaissance, LLM analysis, and multi-channel notification.

Architecture

┌─────────────────┐     ┌──────────────────┐     ┌────────────────┐     ┌──────────────┐
│ n8n Schedule    │────▶│ Flask Scan       │────▶│ Anthropic API  │────▶│ Telegram Bot │
│ Trigger (daily) │     │ Server (nmap)    │     │ (Claude Opus)  │     │              │
└─────────────────┘     └──────────────────┘     └────────────────┘     └──────────────┘

Components:

• n8n workflow (n8n-workflow.json): visual orchestration, cron + manual triggers, HTTP request nodes chained to Telegram
• scan_server.py: lightweight Flask webhook that wraps nmap and exposes /scan to the n8n container
• scan.py: standalone CLI version that runs the full pipeline end-to-end without n8n (for local testing and fallback)

Tech Stack

• Python 3.12 + Flask
• nmap 7.99
• n8n (self-hosted via Docker)
• Anthropic Claude API (claude-opus-4-5)
• Telegram Bot API

Setup

Requires macOS with Homebrew, Docker Desktop, and Python 3.10+.

# 1. Install dependencies
brew install nmap node python git
brew install --cask docker

# 2. Clone and enter project
git clone <your-repo-url>
cd sec-scan-automator

# 3. Python environment
python3 -m venv venv
source venv/bin/activate
pip install requests python-dotenv anthropic flask

# 4. Configure secrets
cp .env.example .env
# Edit .env with your ANTHROPIC_API_KEY, TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID

# 5. Start the Flask scan server (terminal 1)
python scan_server.py

# 6. Start n8n (terminal 2)
docker volume create n8n_data
docker run -d --name n8n --restart unless-stopped -p 5678:5678 \
  -v n8n_data:/home/node/.n8n \
  docker.n8n.io/n8nio/n8n

# 7. Import the workflow
# Open http://localhost:5678
# Create owner account
# Workflows > Import from File > select n8n-workflow.json
# Set up Telegram credentials in the "Send a text message" node
# Set up API key header in the "Claude Analysis" node
# Publish the workflow

Standalone Mode

To run without n8n:

source venv/bin/activate
python scan.py                       # uses SCAN_TARGET from .env
python scan.py scanme.nmap.org       # override target

Demo Target

All examples use scanme.nmap.org, Nmap Project's intentionally-maintained public scanning target. Do not point this tool at networks you do not own or have explicit written permission to test.

What the Report Looks Like

🛡️ Security Scan Report
Generated: 2026-04-24 09:00

*Target:* scanme.nmap.org (45.33.32.156)
*Risk Level:* High

*Open Ports and Services:*
- 22/tcp  SSH  OpenSSH 6.6.1p1 Ubuntu 2ubuntu2.13  SEVERELY OUTDATED
- 80/tcp  HTTP Apache 2.4.7 (Ubuntu)              SEVERELY OUTDATED
- 53/tcp  DNS  filtered

*Key Findings:*
1. OpenSSH 6.6.1p1 (2014) vulnerable to CVE-2016-0777, CVE-2015-5600, CVE-2016-10009
2. Apache 2.4.7 missing 10+ years of security patches (CVE-2021-41773, CVE-2021-44790)
3. OS appears to be Ubuntu 14.04 (EOL April 2019)
...

Roadmap

• Multi-target scanning from a configurable list
• Historical diffing (alert on new open ports or service version changes)
• Integration with a vulnerability database for CVE enrichment
• Severity-based routing (critical findings to a separate channel)
• Scan policy templates (recon vs full assessment vs compliance)

Project Structure

sec-scan-automator/
├── scan.py                 # Standalone CLI pipeline
├── scan_server.py          # Flask webhook wrapper for n8n
├── n8n-workflow.json       # Exported n8n workflow definition
├── .env.example            # Template for secrets
├── .gitignore
├── README.md
└── scan-results/           # Timestamped raw nmap outputs (gitignored)

License

MIT