🛡️ Cyber Claude

AI-Powered Defensive Cybersecurity Agent with Guided Workflows

Perfect for Beginners & Security Professionals

An AI-powered cybersecurity agent built with the Claude Agent SDK, designed exclusively for defensive security operations. Features 10 pre-configured workflows for guided security tasks, web application vulnerability testing, OSINT reconnaissance, network traffic analysis (pcap), system hardening, and AI-powered security analysis.

🎯 NEW: Guided Workflows - Step-by-step security tasks perfect for learning and fast execution! 🔒 Defensive-Only - No exploitation, credential harvesting, or offensive capabilities 🤖 AI-Powered - Claude, OpenAI GPT-5.1, Gemini (cloud) or DeepSeek-R1, Gemma (local) for intelligent analysis 🏠 Privacy Option - Run 100% locally with Ollama (no cloud, no API keys, offline capable)

---

🚀 Getting Started (60 seconds!)

Option 1: Cloud Models (Fastest Setup)

# 1. Install
npm install

# 2. Configure (add your API key)
cp .env.example .env
# Edit .env and add ANTHROPIC_API_KEY, OPENAI_API_KEY, or GOOGLE_API_KEY

# 3. Build
npm run build

# 4. Start with guided workflows!
cyber-claude

# Choose "Quick Security Health Check" (2-3 min)
# AI will scan your system and give you recommendations

Option 2: Local Models (Privacy-Focused)

# 1. Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# 2. Pull a model
ollama pull gemma3:4b  # Quick option (2GB)
# OR
ollama pull deepseek-r1:8b  # Better reasoning (6GB)

# 3. Install Cyber Claude
npm install && npm run build

# 4. Use with local model (no API key needed!)
cyber-claude scan --model gemma3-4b

First time? - Cloud users: Try the "Quick Security Health Check" workflow - Local users: Start with gemma3-4b for fast responses, upgrade to deepseek-r1-8b for better analysis

---

📖 Documentation

User Guides

• Complete Workflows & Playbook Guide - Comprehensive guide to getting the most out of Cyber Claude
• Agent Modes Guide - Detailed guide to using different agent modes effectively
• Quick Start Guide - Fast track to getting started
• Security Policy - Security reporting and best practices

Technical Documentation

• Technical Architecture - Architecture, development, and implementation details
• Project Structure - Codebase organization and file structure
• Professional Enhancements - IOC extraction, MITRE ATT&CK mapping, evidence preservation
• Project Assessment - Independent security audit and assessment

Version History

• Changelog - Version history and release notes
• Capabilities Overview - Complete feature list and capabilities matrix

---

🚀 Quick Start

Prerequisites

Required: - Node.js 18+ - npm or yarn

Choose at least one AI provider: - Cloud (API-based): - Anthropic API key (Get one here) for Claude models, OR - Google API key (Get one here) for Gemini models - Local (Privacy-focused): - Ollama (Install here) for DeepSeek-R1 and Gemma models - 8-16GB RAM recommended for local models

Installation

# Clone the repository
git clone <your-repo-url>
cd cyber_claude

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env and add your ANTHROPIC_API_KEY or GOOGLE_API_KEY

# Build the project
npm run build

# Run in development mode
npm run dev

Basic Usage

🎯 FASTEST START: Pre-Configured Workflows (Perfect for Beginners!)

# Start with guided workflows - best way to get started!
cyber-claude flows

# Try a beginner workflow
cyber-claude flows --difficulty beginner

# Quick security check (takes 2-3 minutes)
# The flow will guide you through:
# 1. Select "Quick Security Health Check"
# 2. AI scans your system automatically
# 3. Get clear security recommendations
# 4. Done!

🌟 Interactive Session (Recommended for Power Users)

# Start interactive session (default command)
cyber-claude

# Inside session, just type commands:
> flows                   # Browse workflows (easiest!)
> scan                    # Quick security check
> scan full               # Full system scan
> webscan https://example.com  # Scan web application
> pcap capture.pcap       # Analyze network traffic
> harden                  # Check hardening
> mode redteam            # Switch to red team mode
> model                   # Select AI model
> What are the top 3 risks on my system?  # Natural chat
> exit                    # Leave session

📋 One-Off Commands (For Scripts & Automation)

# Perform security scan
cyber-claude scan
cyber-claude scan --quick
cyber-claude scan --network --model opus-4

# Web application scanning
cyber-claude webscan https://example.com
cyber-claude webscan --full https://myapp.local

# OSINT reconnaissance
cyber-claude recon example.com --full
cyber-claude recon username john_doe
cyber-claude recon breach user@example.com

# Network traffic analysis
cyber-claude pcap capture.pcap
cyber-claude pcap --mode threat-hunt suspicious.pcap
cyber-claude pcap --filter tcp --port 443 traffic.pcap
cyber-claude pcap --packets --export-json report.json capture.pcap

# Check system hardening
cyber-claude harden --model haiku-4

# One-off chat mode
cyber-claude chat --mode redteam

---

🆕 What's New

v0.7.0 - Smart Contract Security (NEW!)

📜 Web3 / Smart Contract Security Scanner

Full-featured Solidity smart contract vulnerability detection based on DeFiHackLabs real-world exploit patterns:

# Scan a Solidity contract
cyber-claude web3 scan contract.sol

# Full audit with AI analysis
cyber-claude web3 audit MyContract.sol

# Check available Web3 tools
cyber-claude web3 tools

# Interactive mode with smartcontract focus
cyber-claude interactive -m smartcontract

11 Vulnerability Detectors: - 🔄 Reentrancy - Cross-function and cross-contract reentrancy - 🔐 Access Control - Missing modifiers, unprotected functions - 🔢 Integer Overflow - Arithmetic vulnerabilities (pre-0.8.0) - 📝 State Modification - Unexpected state changes after external calls - ⚡ Flash Loan - Flash loan attack vectors - 📊 Oracle Manipulation - Price oracle vulnerabilities - 🎯 Precision Loss - Division-before-multiplication, unsafe downcasts - 📞 Arbitrary Call - User-controlled call targets, delegatecall risks - 💾 Storage Collision - Non-EIP1967 proxies, missing storage gaps - ⏰ Timestamp Dependence - Block timestamp manipulation (SWC-116) - 🎲 Weak Randomness - Predictable randomness sources (SWC-120)

Real-World Exploit References: - Links to DeFiHackLabs exploit reproductions ($200M+ in documented exploits) - Includes: Hundred Finance, Qubit Finance, Multichain, Audius, Furucombo, Fomo3D

New Agent Mode: - smartcontract mode (📜) - Specialized for DeFi security and smart contract auditing

---

v0.6.0 - Autonomous Agent Mode (Development)

🤖 NEW: Autonomous AI Execution - Advanced Users

The new auto command enables fully autonomous task execution with AI-powered planning and execution:

cyber-claude auto "scan example.com for vulnerabilities"
cyber-claude auto "analyze this network for suspicious activity" --mode blueteam
cyber-claude auto "gather OSINT on target.com" --thinking --max-steps 15

Key Features: - 🧠 AI Planning - Automatically breaks down tasks into executable steps - 🔄 Self-Correction - Reflects on results and adapts strategy - 🎯 Multi-Tool - Intelligently selects and chains security tools - ⚡ Extended Thinking - Claude's extended thinking for complex planning - 🛡️ Safety Controls - Approval workflows for high-risk operations

NOTE: MCP (Model Context Protocol) security tools have been removed. Built-in tools provide comprehensive coverage for all scanning needs.

🔧 NEW: Enhanced Security Toolkit

Four new npm-based security tools have been integrated to replace the non-functional MCP tools:

1. DependencyScanner (retire.js) - 📦 Scans JavaScript dependencies for known vulnerabilities - 🔍 CVE detection and severity classification - 📊 Comprehensive vulnerability reporting - ⚡ No API keys required

2. SSLAnalyzer (ssl-checker) - 🔒 SSL/TLS certificate analysis - ⏰ Expiration monitoring and alerts - 🎯 Risk scoring and security recommendations - ✅ Certificate chain validation

3. ScreenshotTool (Puppeteer) - 📸 Automated website screenshots - 🔍 Technology detection (React, Vue, WordPress, etc.) - 🌐 Full-page or viewport captures - 🎨 Visual reconnaissance capabilities

4. ExternalToolManager - 🛠️ Auto-detects 12 external CLI security tools (nmap, nuclei, ffuf, sqlmap, etc.) - 📊 Version checking and availability status - 📚 Installation guides for missing tools - 🔄 Tool execution wrapper

All tools work out-of-the-box with zero configuration!

v0.5.1 - Workflows & Enhanced User Experience

🎯 Pre-Configured Workflows - Perfect for Beginners!

The flows command provides guided, step-by-step workflows for common security tasks:

cyber-claude flows                        # Interactive menu
cyber-claude flows --category security    # Show security workflows
cyber-claude flows --difficulty beginner  # Beginner-friendly workflows

10 Pre-Built Workflows: - 🛡️ Quick Security Health Check (2-3 min, beginner) - Desktop security scan - 🌐 Website Security Audit (3-5 min, beginner) - OWASP Top 10 assessment - 🔍 Domain Intelligence Gathering (3-5 min, beginner) - Full OSINT scan - 🚨 Incident Response Triage (5-7 min, intermediate) - Security incident analysis - 📡 Network Traffic Threat Hunting (4-6 min, intermediate) - PCAP analysis - 🕵️ Full OSINT Investigation (5-10 min, intermediate) - Deep reconnaissance - 🔒 System Hardening Guide (10-15 min, intermediate) - Security improvements - 🎯 Red Team Reconnaissance (10-15 min, advanced) - External recon - 🚩 CTF Web Challenge Solver (10-20 min, advanced) - CTF assistance - 📚 Learn OSINT Basics (15-20 min, beginner) - Interactive tutorial

Why Workflows? - 🎓 Beginner-Friendly: Guided step-by-step experiences - ⚡ Fast: Pre-configured for common tasks - 📖 Educational: Learn security concepts while using them - 🎯 Goal-Oriented: Each workflow solves a specific problem

v0.5.0 - OSINT Reconnaissance Suite

🔍 NO API KEYS REQUIRED!

• 📡 10 Comprehensive OSINT Tools: All free, no API keys needed! ```bash # Full reconnaissance cyber-claude recon example.com --full

# Domain-focused scan cyber-claude recon example.com --domain

# Username enumeration cyber-claude recon john_doe --person

# Individual tools cyber-claude recon subdomains example.com cyber-claude recon breach user@example.com cyber-claude recon tech https://example.com cyber-claude recon username john_doe ```

• 🛠️ Included Tools (All FREE):
• DNS Reconnaissance - A/AAAA/MX/NS/TXT/SOA records, reverse DNS
• WHOIS Lookup - Domain registration, age, expiration analysis
• Subdomain Enumeration - Certificate transparency + DNS brute force
• Email Harvesting - Website scraping + common patterns
• Username Enumeration - 35+ platforms (GitHub, Twitter, Instagram, etc.)
• Breach Data Lookup - Have I Been Pwned integration
• Technology Detection - Web server, CMS, frameworks (50+ signatures)
• Wayback Machine - Historical snapshots and domain history
• IP Geolocation - Country/city/ISP lookup

• Reverse IP Lookup - Find other domains on same IP

• 🎯 Professional Features:

• Risk scoring and assessment
• Attack surface identification
• Data exposure analysis
• Export to JSON/Markdown
• No rate limits (free tier APIs)
• Privacy-respecting (passive only)

Professional Features: - 🎯 IOC Extraction: Automatic extraction with STIX 2.1 export - 🗺️ MITRE ATT&CK: Technique mapping and threat intelligence - 🔬 Evidence Preservation: Chain of custody with triple hash verification (MD5/SHA1/SHA256) - 📊 Forensics: Forensically sound metadata tracking

📦 Network Traffic Analysis - AI-Powered Wireshark!

• 🔍 PCAP Analysis: Analyze network capture files with AI-powered insights! ```bash cyber-claude pcap capture.pcap --extract-iocs --mitre cyber-claude pcap --mode threat-hunt suspicious.pcap --preserve-evidence cyber-claude pcap --filter tcp --port 443 traffic.pcap

  pcap network-capture.pcap # Works in interactive session! ```

• 🎯 Wireshark-Inspired Features: Protocol dissection, display filters, statistics

• 📊 Comprehensive Analysis: Conversations, endpoints, DNS queries, HTTP requests
• 🚨 Threat Detection: Port scans, suspicious ports, anomaly detection
• 📈 Export Options: JSON, Markdown, CSV formats
• 🔬 Analysis Modes: Quick, full, or threat-hunt analysis

**Previous: v0.3.0 - Web Security Testing + Multi-Provider