██████╗██╗   ██╗██████╗ ███████╗██████╗ ███████╗███╗   ██╗████████╗██████╗ ██╗   ██╗
 ██╔════╝╚██╗ ██╔╝██╔══██╗██╔════╝██╔══██╗██╔════╝████╗  ██║╚══██╔══╝██╔══██╗╚██╗ ██╔╝
 ██║      ╚████╔╝ ██████╔╝█████╗  ██████╔╝███████╗██╔██╗ ██║   ██║   ██████╔╝ ╚████╔╝ 
 ██║       ╚██╔╝  ██╔══██╗██╔══╝  ██╔══██╗╚════██║██║╚██╗██║   ██║   ██╔══██╗  ╚██╔╝  
 ╚██████╗  ██║   ██████╔╝███████╗██║  ██║███████║██║ ╚████║   ██║   ██║  ██║   ██║   
  ╚═════╝  ╚═╝   ╚═════╝ ╚══════╝╚═╝  ╚═╝╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚═╝  ╚═╝   ╚═╝   
                                                                                        
          🔐 AI-Powered Autonomous Ethical Hacking Agent 🔐

CyberSentry: Autonomous Ethical Website Security Auditor

---

📋 Table of Contents

• Overview
• ✨ Features
• 🎯 Architecture
• 🛠️ Tech Stack
• 📦 Installation
• 🚀 Usage
• 🔍 Real Findings
• 🗺️ Roadmap
• 👨‍💻 About the Developer
• ⚖️ Legal & Ethical Disclaimer
• 📄 License

---

Overview

CyberSentry is an autonomous AI-powered security auditing agent designed for ethical website penetration testing and vulnerability assessment. Powered by NVIDIA NIM running Llama 3.1 70B, it implements a ReAct loop architecture (Think → Act → Observe → Repeat) to intelligently coordinate 8 advanced security scanning tools.

Unlike traditional security scanners, CyberSentry reasons about findings, adapts its approach based on results, and generates professional bug-bounty style security reports with actionable recommendations.

Key Innovation

• Autonomous Decision-Making: Uses Llama 3.1 70B to reason about security findings and adjust scanning strategy
• Real-time Terminal Visualization: Live xterm windows with hacker-themed green-on-black UI
• 8 Integrated Security Tools: Robots/Sitemap, Tech Detection, HTTP Headers, SSL Analysis, Cookie Audit, Directory Fuzzing, CORS Testing, Nmap Scanning
• Professional Reporting: Generates industry-standard security audit reports with CVSS-style severity ratings

---

✨ Features

Feature	Description
🤖 AI-Powered Reasoning	Llama 3.1 70B makes autonomous decisions about which tools to run and how to interpret results
🔄 ReAct Loop	Implements Think → Act → Observe → Reason cycle for intelligent tool orchestration
🎯 8 Security Tools	Robots/Sitemap Recon, Tech Stack Detection, HTTP Header Analysis, SSL Certificate Checking, Cookie Auditing, Directory Fuzzing, CORS Analysis, Nmap Port Scanning
📊 Real-time UI	Rich terminal interface with color-coded severity indicators and live progress
📈 Professional Reports	Generates markdown security reports with findings, severity levels, and remediation steps
🛡️ Ethical Focus	Built with explicit ethical guidelines and requires authorized target specification
⚡ Efficient Scanning	Intelligent tool coordination reduces scanning time vs. running all tools sequentially
🔒 Secure Credential Management	Uses environment variables for API key management

---

🎯 Architecture

┌─────────────────────────────────────────────────────────────┐
│                    User Input (Target URL)                   │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│           ReAct Agent Loop (Autonomous)                      │
│  ┌──────────────────────────────────────────────────────┐   │
│  │ 1️⃣  THINK: LLM analyzes target & plans tools        │   │
│  ├──────────────────────────────────────────────────────┤   │
│  │ 2️⃣  ACT: Execute planned security tools             │   │
│  │    ├─ Robots/Sitemap Parser                          │   │
│  │    ├─ Tech Stack Detector (Wappalyzer)              │   │
│  │    ├─ HTTP Header Analyzer                           │   │
│  │    ├─ SSL Certificate Checker                        │   │
│  │    ├─ Cookie Auditor                                 │   │
│  │    ├─ Directory Fuzzer                               │   │
│  │    ├─ CORS Policy Tester                             │   │
│  │    └─ Nmap Port Scanner                              │   │
│  ├──────────────────────────────────────────────────────┤   │
│  │ 3️⃣  OBSERVE: Collect tool outputs & results         │   │
│  ├──────────────────────────────────────────────────────┤   │
│  │ 4️⃣  REASON: LLM interprets findings & decides next  │   │
│  │    ├─ Run more focused scans?                        │   │
│  │    ├─ Deep dive on vulnerabilities?                 │   │
│  │    └─ Generate final report?                         │   │
│  └──────────────────────────────────────────────────────┘   │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│        Professional Security Audit Report (Markdown)         │
│  ├─ Findings by Severity (Critical/High/Medium/Low)         │
│  ├─ CVSS Scores & Risk Assessment                           │
│  ├─ Remediation Recommendations                             │
│  └─ Executive Summary                                        │
└─────────────────────────────────────────────────────────────┘

For detailed architecture documentation, see docs/ARCHITECTURE.md

---

🛠️ Tech Stack

Component	Technology
Language	Python 3.13
LLM Engine	NVIDIA NIM (Llama 3.1 70B)
Agent Pattern	ReAct (Reasoning + Acting)
Terminal UI	Rich Python library
Network Tools	Nmap, requests, ssl, socket, subprocess
Security Tools	Robots parser, sslyze, requests_toolbelt
Environment	Kali Linux / WSL2 Ubuntu
API Integration	OpenAI-compatible NVIDIA NIM API

---

📦 Installation

Prerequisites

• Python 3.13+
• pip (Python package manager)
• NVIDIA NIM API Key (Get free access)
• Nmap (for port scanning)
• Kali Linux or WSL2 Ubuntu (recommended for full tool support)

Step 1: Clone Repository

git clone https://github.com/prutxvi/cybersentry.git
cd cybersentry

Step 2: Create Virtual Environment

# On Kali Linux / Ubuntu
python3 -m venv venv
source venv/bin/activate

# On Windows (WSL2)
python -m venv venv
source venv/Scripts/activate

Step 3: Install Dependencies

pip install -r requirements.txt

Required packages:

• openai - NVIDIA NIM API client
• python-dotenv - Environment variable management
• rich - Beautiful terminal UI
• requests - HTTP requests
• scapy - Network packet manipulation

Step 4: Configure Environment Variables

# Copy example configuration
cp .env.example .env

# Edit .env with your NVIDIA API key
nano .env

Add your NVIDIA NIM API key:

NVIDIA_API_KEY=nvapi-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TARGET_URL=https://your-own-website.com

Step 5: Install System Dependencies

On Kali Linux:

sudo apt update
sudo apt install nmap xterm -y

On WSL2 Ubuntu:

sudo apt update
sudo apt install nmap xterm -y

---

🚀 Usage

Basic Usage

# Activate virtual environment
source venv/bin/activate

# Run security audit on configured target
python agent.py

# Expected output:
#   ✓ Tool 1/8: Robots.txt & Sitemap Analysis
#   ✓ Tool 2/8: Tech Stack Detection
#   ✓ Tool 3/8: HTTP Header Analysis
#   ✓ Tool 4/8: SSL Certificate Check
#   ✓ Tool 5/8: Cookie Audit
#   ✓ Tool 6/8: Directory Fuzzing
#   ✓ Tool 7/8: CORS Testing
#   ✓ Tool 8/8: Nmap Port Scan
#
#   📄 Report saved to: report_20260503_021648.md

Interactive Mode

The agent will:

1. Display its reasoning in the terminal as it decides which tools to run
2. Show real-time tool execution in xterm windows with live output
3. Ask follow-up questions about findings that need deeper investigation
4. Summarize results after all tools complete
5. Generate professional report with findings and recommendations

Output Files

report_YYYYMMDD_HHMMSS.md  ← Professional security audit report

The report includes:

• Executive summary
• Findings grouped by severity
• Technical details of each vulnerability
• CVSS scores (where applicable)
• Remediation recommendations
• Scan metadata (tool versions, timestamp, scope)

---

🔍 Real Findings

Scan Target: example.com (May 2, 2026)

This is a real security audit performed on the developer's portfolio website. Note: Scan was authorized by the domain owner.

Finding	Severity	CVSS	Status
Missing Content-Security-Policy Header	Medium	5.3	⚠️ Unpatched
Server Header Reveals Vercel Platform	Low	2.7	ℹ️ Info
SSL Certificate Expires June 2, 2026	Medium	5.9	⚠️ 30 Days
WordPress Paths Detected (403 Errors)	Low	3.1	ℹ️ Hardened
Missing X-Content-Type-Options Header	Low	2.7	⚠️ Unpatched

Detailed Findings

[1] Missing Content-Security-Policy (CSP) Header (Medium Severity)

• Risk: Without CSP, the site is vulnerable to XSS (Cross-Site Scripting) attacks
• Finding: Response headers lack Content-Security-Policy directive
• CVSS v3.1: 5.3 (Medium)
• Recommendation: Implement CSP header with strict directives

  Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'
  

[2] Server Header Reveals Technology Stack (Low Severity)

• Risk: Attackers learn site runs on Vercel, enabling targeted attacks
• Finding: Server: Vercel header exposed in HTTP response
• CVSS v3.1: 2.7 (Low)
• Recommendation: Remove or obfuscate server header

  # In Vercel vercel.json
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        {
          "key": "Server",
          "value": "Web Server"
        }
      ]
    }
  ]
  

[3] SSL Certificate Expires Soon (Medium Severity)

• Risk: Service interruption, potential MITM attacks during renewal
• Finding: Certificate valid until June 2, 2026 (30 days remaining)
• CVSS v3.1: 5.9 (Medium)
• Recommendation: Renew certificate immediately (auto-renewal via Vercel)

[4] WordPress Paths Detected (Low Severity)

• Risk: Potential information disclosure; 403 responses leak existence of WP paths
• Finding: Paths detected: /wp-admin, /wp-includes, /wp-content (all return 403)
• CVSS v3.1: 3.1 (Low)
• Recommendation: These are hardened and return 403, which is good. No action needed.

[5] Missing X-Content-Type-Options Header (Low Severity)

• Risk: MIME-type sniffing attacks
• Finding: X-Content-Type-Options: nosniff header not present
• Recommendation: Add header to prevent MIME-sniffing

  X-Content-Type-Options: nosniff
  

Scan Statistics

• Scan Date: May 2, 2026
• **Total Tools