Guardian Ops

A comprehensive network security platform that integrates automated vulnerability scanning, CVE detection, and remote firewall management. Built for seamless user interaction via AI assistants (Puch AI), with a web dashboard for audit logs and a Discord bot for instant port blocking.

Guardian Ops empowers users to scan their networks, detect threats, and respond in real-time—without leaving their chat interface.

What It Does

Guardian Ops provides end-to-end security operations through a conversational AI interface:

Core Workflow

1. User Interaction: Connect via Puch AI (e.g., WhatsApp) and provide your IP/hostname. Choose a scan type (quick/full/port check/vuln/network discovery).
2. Scanning & Detection: The MCP server performs Nmap-based scans, detects open ports/services, and chains CVE searches across CIRCL, NVD, and Vulners APIs.
3. Reporting: Instant reports with open ports, services, and potential vulns. If vulnerabilities are found, alerts the user.
4. Dashboard Access: View scan history and details via a secure web dashboard.
5. Remediation: For detected vulns on open ports, get a direct link to authorize and use the Discord bot to block risky ports remotely.

Key Features

• Conversational Scanning: Natural language commands like "OG quick scan on my-ip.com" via Puch AI.
• Multi-API CVE Chaining: Aggregates vulns from CIRCL (free), NVD (key optional), and Vulners (key optional) with deduplication.
• Audit Logging: Per-user SQLite database tracks all scans with timestamps and results.
• Web Dashboard: Dark-themed UI for viewing/deleting logs and scan details.
• Remote Port Management: Discord bot blocks/unblocks TCP ports using iptables (persistent via netfilter-persistent).
• Security-First: Bearer auth for MCP, env-based secrets, input validation, and single-user Discord authorization.
• Background Processing: CVE checks run asynchronously to keep scans fast.

Security & Compliance

• Scans log to a dashboard for audit trails.
• Port blocking uses UFW-compatible iptables chains.
• No sensitive data exposed in responses.
• Rate-limited concurrent requests to avoid API abuse.

Technical Architecture

Components

• MCP Server (mcp_server.py): FastMCP-based server for Puch AI integration. Handles scans with Nmap, CVE queries via httpx, and logging to SQLite.
• Dashboard (dashboard.py): FastAPI app with Jinja2 templates for user-facing logs and details.
• Discord Bot (bot.py): discord.py bot for port management, executing shell scripts.
• Shell Scripts (scripts/): block_port.sh and unblock_port.sh for iptables rules.
• System Service (services/capstonebot.service): Systemd for bot auto-start.
• Database: SQLite (guardian_scans.db) for scan logs.

Data Flow

User (Puch AI) → MCP Server (Scan Request) → Nmap Scan + CVE APIs → Report + Vuln Alert
                  ↓
Dashboard (Logs) ← SQLite ← Scan Results
                  ↓ (If Vulns)
User → Discord Bot (Authorize) → Shell Scripts → iptables → Persistent Rules

Tech Stack

• Backend: Python 3.8+, FastMCP, FastAPI, discord.py, Nmap, httpx.
• Database: SQLAlchemy + SQLite.
• APIs: CIRCL CVE, NVD, Vulners.
• Frontend: Jinja2, HTML/CSS (dark theme, Poppins font).
• OS: Ubuntu 20.04+ (iptables, netfilter-persistent).

Prerequisites

• Ubuntu Server 20.04+.
• Python 3.8+.
• Nmap installed (sudo apt install nmap).
• netfilter-persistent for rule persistence (sudo apt install iptables-persistent).
• Discord Bot Token (create at Discord Developer Portal).
• Optional: NVD/Vulners API keys for enhanced CVE searches.
• sudo privileges for iptables.

Installation

1. Clone the Repository

git clone <your-repo-url>
cd guardian-ops

2. Environment Setup

Create .env in the root:

# MCP Server
AUTH_TOKEN=your_mcp_auth_token_here
MY_NUMBER=your_phone_number_here  # e.g., 919876543210
VULNERS_API_KEY=your_vulners_key_optional
NVD_API_KEY=your_nvd_key_optional
DASHBOARD_URL=http://your-server-ip:8000  # Update with your dashboard URL

# Discord Bot
DISCORD_TOKEN=your_discord_bot_token_here
AUTHORIZED_USER_ID=your_discord_user_id_here  # Numeric user ID

Load env: source .env (or use python-dotenv).

3. Install Dependencies

# MCP Server & Dashboard
pip install -r requirements-mcp.txt  # Includes fastmcp, nmap, httpx, sqlalchemy, fastapi, etc.

# Discord Bot
cd discord-bot
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt  # discord.py, python-dotenv

4. Database Setup

The SQLite DB auto-creates on first scan. Run migrations if needed:

python -c "from mcp_server import engine, Base; Base.metadata.create_all(engine)"

5. Discord Bot Scripts

cd discord-bot/scripts
chmod +x block_port.sh unblock_port.sh

6. System Services

For Discord Bot:

sudo cp discord-bot/services/capstonebot.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable capstonebot.service
sudo systemctl start capstonebot.service

For MCP Server & Dashboard: Run manually or via systemd (see below).

7. Start Services

• MCP Server: python mcp_server.py (runs on :8086).
• Dashboard: python dashboard.py (runs on :8000).
• Test: sudo journalctl -u capstonebot.service -f for bot logs.

Usage

User Workflow (Via Puch AI/WhatsApp)

1. Message "hi" to Guardian Ops (OG) for the menu.
2. e.g., "OG quick scan on 192.168.1.100" → Gets scan report.
3. If vulns found: Report includes "Go to Discord bot: https://discord.com/oauth2/authorize?client_id=1436272504128929852" to authorize and block ports.
4. View history: Use dashboard link in reports (e.g., http://your-server:8000).

Scan Commands

Command	Example	Description
Quick Scan	OG quick scan on scanme.nmap.org	Fast common ports + basic vulns.
Full Scan	OG full scan on example.com	Thorough OS/service/vuln scan.
Port Check	OG port check on example.com port 80	Specific port status + service.
Vuln Scan	OG vuln scan apache 2.4	CVE search for service/version.
Network Discovery	OG network discovery 192.168.1.0/24	Find active hosts in subnet.

Discord Bot Commands (Post-Scan Remediation)

Invite bot: https://discord.com/oauth2/authorize?client_id=1436272504128929852
(Authorize only once; commands restricted to your user ID.)

Command	Usage	Description
!ping	!ping	Bot responsiveness.
!blockport	!blockport 8080	Block TCP port (persistent).
!unblockport	!unblockport 8080	Unblock port.
!helpme	!helpme	Command list.

Example:

User: !blockport 8080
Bot:  Blocked TCP port 8080.

Dashboard

• Access: http://your-server:8000
• Login: Enter Puch User ID.
• Features: View/delete logs, scan details.

Security Considerations

• Auth: MCP uses bearer tokens; Discord limits to one user ID.
• Validation: IP/port/service inputs sanitized; scans limited (e.g., max 256 hosts).
• Persistence: iptables rules saved via netfilter-persistent.
• APIs: Fallback to free CIRCL if keys invalid.
• Logs: No sensitive data stored; user-owned DB.

Warning: Scans may trigger IDS/IPS. Use responsibly on authorized networks. Port blocking requires sudo—test in safe env.

Project Structure

guardian-ops/
├── nmap_puch_mcp.py             # Puch AI MCP server
├── dashboard.py               # FastAPI dashboard
├── requirements.txt       # MCP + dashboard deps
├── templates/                 # HTML: login.html, dashboard.html, scan_detail.html
├── discord-bot/
│   ├── bot.py                 # Discord bot
│   ├── requirements.txt       # Bot deps
│   ├── .env                   # Bot env (or root)
│   ├── scripts/
│   │   ├── block_port.sh
│   │   └── unblock_port.sh
│   └── services/
│       └── capstonebot.service
└── guardian_scans.db          # Auto-generated SQLite

Troubleshooting

• MCP Won't Start: Check AUTH_TOKEN/MY_NUMBER; verify Nmap (nmap --version).
• Scans Timeout: Increase timeouts or use faster targets (e.g., scanme.nmap.org).
• Bot Unauthorized: Confirm AUTHORIZED_USER_ID (numeric, via Discord dev tools).
• Dashboard No Logs: Ensure Puch User ID matches; check SQLite.
• Vulns Not Found: Add API keys; CIRCL is default fallback.
• Logs: journalctl -u capstonebot (bot); console for MCP/dashboard.

Customization

• Add Scans: Extend @mcp.tool in mcp_server.py; update guardian_ops parser.
• UDP Support: Modify shell scripts: iptables -I ufw-before-input -p udp --dport $PORT -j DROP.
• Dashboard: Add auth (e.g., JWT) or export logs.
• Alerts: Integrate email/SMS for high-CVSS vulns.

License

Educational capstone project—MIT License. Use responsibly.

Support

• Issues: Check troubleshooting; verify prereqs/permissions.
• Community: Discord bot for testing; Puch AI for scans.
• Enhancements: PRs welcome!

---

Note: Guardian Ops handles powerful security tools. Always comply with laws and obtain permission for scans. Test on isolated networks first.