# 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.**

[![Python](https://img.shields.io/badge/Python-3.8%2B-blue)](https://www.python.org/) [![Discord](https://img.shields.io/badge/Discord-Bot-purple)](https://discord.com/) [![FastAPI](https://img.shields.io/badge/FastAPI-0.100%2B-brightgreen)](https://fastapi.tiangolo.com/)

## 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](https://discord.com/developers/applications)).
- Optional: NVD/Vulners API keys for enhanced CVE searches.
- sudo privileges for iptables.

##  Installation

### 1. Clone the Repository
```bash
git clone <your-repo-url>
cd guardian-ops
```

### 2. Environment Setup
Create `.env` in the root:
```env
# 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
```bash
# 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:
```bash
python -c "from mcp_server import engine, Base; Base.metadata.create_all(engine)"
```

### 5. Discord Bot Scripts
```bash
cd discord-bot/scripts
chmod +x block_port.sh unblock_port.sh
```

### 6. System Services
For Discord Bot:
```bash
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.