<div align="center">

# 🛡️ AynOps
### AI-Powered Cybersecurity Reconnaissance Platform

[![Python](https://img.shields.io/badge/Python-3.12+-blue?style=flat-square&logo=python)](https://python.org)
[![FastMCP](https://img.shields.io/badge/FastMCP-3.3+-green?style=flat-square)](https://github.com/jlowin/fastmcp)
[![ArmorIQ](https://img.shields.io/badge/ArmorIQ-SDK-purple?style=flat-square)](https://armoriq.ai)
[![License](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)](LICENSE)
[![Hackathon](https://img.shields.io/badge/NeuroX_Hackathon-2026-red?style=flat-square)]()

**Talk to Claude. Get a full threat intelligence report. Ethically enforced. Audit-ready.**

[Features](#features) • [Architecture](#architecture) • [Quick Start](#quick-start) • [Demo](#demo) • [Team](#team)

</div>

---

## The Problem

Security reconnaissance requires 6+ different tools, hours of manual work, and deep CLI expertise. Junior analysts miss critical correlations. There's no ethical enforcement preventing unauthorized scans. And there's zero audit trail for compliance.

## The Solution

AynOps is a Model Context Protocol (MCP) server that gives Claude real-time cybersecurity reconnaissance capabilities — wrapped with ArmorIQ policy enforcement and cryptographic audit logging.

**You type in plain English. AynOps handles the rest.**

```
"Run a threat analysis on example.com"
```
→ ArmorIQ verifies the target is authorized  
→ 10 recon tools run in parallel  
→ Claude correlates findings across all tools  
→ Structured threat report with risk score and remediation roadmap  
→ Every action logged to ArmorIQ's tamper-proof audit trail  

---

## What Makes AynOps Different

| | Traditional Tools (Nmap, Shodan) | AynOps |
|---|---|---|
| Interface | CLI expertise required | Plain English conversation |
| Analysis | Raw data dumps | AI-correlated threat intelligence |
| Ethics | No enforcement | ArmorIQ policy gate on every call |
| Audit | Manual logging | Cryptographic audit trail (automatic) |
| Speed | Run tools one by one | 10 tools in parallel |
| CVEs | Separate lookup | Auto-triggered from detected software |

---

## Features

### 🔍 10 Recon Tools
| Tool | Capability |
|---|---|
| `whois_lookup` | Domain owner, registrar, expiry, name servers |
| `dns_enumeration` | DNS records + subdomain brute-force |
| `port_scan` | Nmap-powered — ports, services, version detection |
| `ssl_inspect` | SSL cert issuer, expiry, cipher, TLS version |
| `tech_stack_detect` | Web server, CMS, CDN, JS frameworks, security headers |
| `cert_transparency` | Subdomain discovery via CT logs |
| `asn_lookup` | ASN, ISP, org, geolocation for any IP/domain |
| `ip_reputation` | AbuseIPDB malicious IP check |
| `cve_lookup` | NVD database — CVEs by software + version |
| `full_recon` | All tools in parallel — one command, complete picture |

### 🧠 AI Threat Correlation (`run_threat_analysis`)
Unlike `full_recon` which summarizes each tool separately, `run_threat_analysis` instructs Claude to **correlate findings across all tools together**:
- Connects detected software versions directly to CVEs
- Links SSL expiry to open HTTPS ports as a compound risk
- Combines missing headers with detected CMS for exploit surface analysis
- Outputs a structured report: Executive Summary → Critical Findings → Risk Score (0–100) → Remediation Roadmap

### 🛡️ ArmorIQ Ethical Enforcement
Every sensitive tool call is gated through ArmorIQ:
1. **`capture_plan`** — cryptographically signs Claude's intent before any tool runs
2. **`get_intent_token`** — mints a short-lived signed token (prevents prompt injection)
3. **Policy enforcement** — unauthorized targets are blocked before your MCP server is ever reached
4. **Audit trail** — every ALLOW/BLOCK decision logged automatically to `platform.armoriq.ai`

```
You: "scan google.com"
ArmorIQ: ❌ BLOCKED — target not in authorized scope
         Audit ID: AQ-0012 | Logged to platform.armoriq.ai
```

---

## Architecture

```
User (Claude Desktop)
        │
        ▼
   Claude AI
   (parses intent, decides which tools to call)
        │
        ▼
 ArmorIQ Policy Gate
 (capture_plan → get_intent_token → verify)
        │
   ┌────┴────┐
   │         │
ALLOW      BLOCK → logged, user notified
   │
   ▼
AynOps MCP Server (streamable-http)
        │
   ┌────┴─────────────────────────┐
   │  Wave 1 (parallel)           │
   ├── whois_lookup               │
   ├── dns_enumeration            │
   ├── port_scan (Nmap)           │
   ├── ssl_inspect                │
   ├── tech_stack_detect          │
   ├── asn_lookup                 │
   ├── cert_transparency          │
   └── headers_analyzer           │
        │                         │
   ┌────┴──────────────┐          │
   │  Wave 2 (parallel)│          │
   ├── cve_lookup       │         │
   └── ip_reputation    │         │
        └──────────────────────────┘
        │
        ▼
 threat_analysis_tool
 (extract_signals + correlation instructions)
        │
        ▼
 Claude generates correlated
 Threat Intelligence Report
        │
        ▼
 ArmorIQ Audit Log
 (tamper-proof, platform.armoriq.ai)
```

---

## Tech Stack

| Layer | Technology |
|---|---|
| AI Interface | Claude (Anthropic) via MCP |
| MCP Framework | FastMCP 3.3+ (streamable-http transport) |
| Language | Python 3.12+ |
| Port Scanning | Nmap |
| Recon Libraries | python-whois, dnspython, ssl, requests |
| CVE Database | NVD (National Vulnerability Database) |
| IP Reputation | AbuseIPDB |
| ASN / Geo | ipapi.com |
| Ethical Layer | ArmorIQ Python SDK |
| Containerization | Docker |
| Deployment | Railway (cloud) |

---

## Quick Start

### Prerequisites
- Python 3.12+
- Nmap installed ([nmap.org/download.html](https://nmap.org/download.html))
- Claude Desktop
- ArmorIQ account ([platform.armoriq.ai](https://platform.armoriq.ai))

### 1. Clone & Install
```bash
git clone https://github.com/gaoharimran29-glitch/AynOps-mcp-hackathon
cd AynOps-mcp-hackathon
pip install -r requirements.txt
```

### 2. Configure Environment
```bash
cp .env.example .env
# Edit .env and add your API keys
```

```env
ABUSEIPDB_API_KEY=your_key     # abuseipdb.com (free)
IP_API_KEY=your_key            # ipapi.com (free)
ARMORIQ_API_KEY=your_key       # platform.armoriq.ai
ANALYST_EMAIL=you@domain.com   # your identity in audit logs
```

### 3. ArmorIQ Setup
```bash
pip install armoriq-sdk
armoriq login
```
Then register your server on `platform.armoriq.ai` → MCP Servers.

### 4. Run Server
```bash
# HTTP mode (for Claude Desktop remote connection / Railway deployment)
uv run server.py

# Local stdio mode (for quick local testing)
fastmcp run server.py
```

### 5. Connect Claude Desktop
```json
{
  "mcpServers": {
    "cybersecurity": {
      "type": "streamable-http",
      "url": "http://localhost:8000/mcp"
    }
  }
}
```

---

## Demo

### Authorized Scan
```
You: "run threat analysis on testphp.vulnweb.com"

ArmorIQ: ✅ Target authorized — intent signed (AQ-0001)

[10 tools run in parallel...]

Claude: 
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🛡️ AynOps Threat Intelligence Report
Target: testphp.vulnweb.com
Risk Score: 87/100 — CRITICAL
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Executive Summary:
testphp.vulnweb.com presents a critically vulnerable attack surface.
Apache 2.4.49 is running on ports 80 and 443, affected by
CVE-2021-41773 (CVSS 9.8) — remote code execution with no auth.
SSL cert expires in 12 days, compounding the exposure window.

🔴 Critical Findings:
• CVE-2021-41773 on Apache 2.4.49 — path traversal → RCE
• SSL expiry in 12 days + HTTPS on port 443 — compound risk

Remediation:
Immediate: Patch Apache to 2.4.51+, renew SSL cert
This week: Add missing security headers (CSP, X-Frame-Options)
```

### Unauthorized Scan (ArmorIQ Block)
```
You: "scan google.com"

❌ BLOCKED by ArmorIQ Policy Gate
Target  : google.com
Reason  : Target not in authorized scope
Audit ID: AQ-0002
Logged  : platform.armoriq.ai/audit-logs
```

### Audit Trail
```
You: "show audit log"

✅ AQ-0001 | run_threat_analysis | testphp.vulnweb.com | ALLOW | gaohar@aynops.local
❌ AQ-0002 | port_scan           | google.com          | BLOCK | gaohar@aynops.local

2 operations: 1 allowed, 1 blocked.
Full trail: platform.armoriq.ai
```

---

## Deployment (Railway)

```bash
npm install -g @railway/cli
railway login
railway init
railway up
```

Set environment variables in Railway dashboard → Variables tab.  
Never commit API keys to your repository.

---

## Team

**Unit313** — NeuroX Hackathon 2026

| Member | Role | College |
|---|---|---|
| Gaohar Imran | Team Lead | Delhi University |
| Mohd Ali | Team Member | Maharaja Surajmal Institute of Technology |

---

## License

MIT — see [LICENSE](LICENSE)

---

<div align="center">

**AynOps — because security intelligence shouldn't require a PhD in CLI tools.**

⭐ Star this repo if you found it useful

</div>