██████╗██╗   ██╗██████╗ ███████╗██████╗ ███████╗███╗   ██╗████████╗██████╗ ██╗   ██╗
 ██╔════╝╚██╗ ██╔╝██╔══██╗██╔════╝██╔══██╗██╔════╝████╗  ██║╚══██╔══╝██╔══██╗╚██╗ ██╔╝
 ██║      ╚████╔╝ ██████╔╝█████╗  ██████╔╝███████╗██╔██╗ ██║   ██║   ██████╔╝ ╚████╔╝ 
 ██║       ╚██╔╝  ██╔══██╗██╔══╝  ██╔══██╗╚════██║██║╚██╗██║   ██║   ██╔══██╗  ╚██╔╝  
 ╚██████╗  ██║   ██████╔╝███████╗██║  ██║███████║██║ ╚████║   ██║   ██║  ██║   ██║   
  ╚═════╝  ╚═╝   ╚═════╝ ╚══════╝╚═╝  ╚═╝╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚═╝  ╚═╝   ╚═╝   
                                                                                        
          🔐 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

🎯 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

📦 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.