hos-vortex 0.1.0
HOS_Vortex - Advanced Red Team Penetration AI Toolkit
Requires Python: >=3.8

# hos_vortex - Advanced Red Team Penetration Testing Framework

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/downloads/)

## Overview

hos_vortex is a comprehensive red team penetration testing framework that integrates traditional penetration testing techniques with AI-powered attack analysis. It provides a modular, extensible platform for authorized security testing, vulnerability assessment, and security research.

**IMPORTANT:** This tool is designed exclusively for authorized security testing and educational purposes with explicit permission from system owners. Unauthorized use is illegal and unethical.

## Features

### Core Modules
- **scan.py** - Comprehensive network and system vulnerability scanning
- **escalate.py** - Privilege escalation techniques for multiple operating systems
- **lateral_move.py** - Network lateral movement with multiple protocol support
- **exfiltrate.py** - Sensitive data identification, extraction, and secure transfer
- **c2_communication.py** - Command and control framework with secure communication
- **ai_engine.py** - AI-powered attack pattern analysis and prediction

### Utility Components
- **config.py** - Flexible configuration management with nested settings
- **logger.py** - Comprehensive logging with rotation, context-awareness, and security events
- **auth.py** - Robust authorization system with API keys and role-based access control

### Key Benefits
- **Modular Architecture**: Independent modules that can be used together or separately
- **AI-Enhanced Analysis**: Advanced pattern recognition and behavior prediction
- **Dual Operation Modes**: Development mode (analysis) and Production mode (testing)
- **Enterprise-Grade Security**: Secure authentication, authorization, and audit logging
- **Extensible Design**: Easy to add new techniques and capabilities

## Installation

### From Source
```bash
git clone https://github.com/yourusername/hos_vortex.git
cd hos_vortex
pip install -r requirements.txt
```

### Requirements
- Python 3.8 or higher
- See `requirements.txt` for detailed dependencies

## Usage

### Running Modules
Each core module can be executed directly:

```bash
# Run vulnerability scan
python -m hos_vortex.core.scan --target 192.168.1.0/24

# Attempt privilege escalation
python -m hos_vortex.core.escalate --target localhost

# Perform lateral movement
python -m hos_vortex.core.lateral_move --source 192.168.1.10 --destination 192.168.1.20

# Extract sensitive data
python -m hos_vortex.core.exfiltrate --target ./data --pattern "password"

# Setup C2 server
python -m hos_vortex.core.c2_communication --mode server --port 443

# Use AI for attack analysis
python -m hos_vortex.ai.ai_engine --action analyze --input logs.txt
```

### Development Mode
Run any module in development mode for blue team analysis and non-intrusive operations:

```bash
python -m hos_vortex.core.scan --target 192.168.1.1 --development
```

### Command-Line Options
All modules support the following common options:
- `--development` - Run in development mode (safer analysis mode)
- `--verbose` - Enable verbose output
- `--debug` - Enable debug level logging
- `--help` - Show detailed help for the module

## Module Details

### Scan Module
The scanning module provides:
- Network service discovery
- Vulnerability detection with CVSS scoring
- Misconfiguration identification
- Weak password detection
- SSL/TLS security assessment
- Web application vulnerability scanning

### Escalate Module
Privilege escalation capabilities include:
- Local privilege escalation checks
- Kernel exploit identification
- Service misconfiguration detection
- Sudo/root access vulnerabilities
- Windows privilege escalation techniques
- Container escape methods

### Lateral Movement Module
Network lateral movement features:
- Credential-based access (password, hash, token)
- Protocol-specific movement (SMB, SSH, RDP)
- Pass-the-hash and pass-the-ticket attacks
- Port forwarding and tunneling
- Lateral movement path analysis

### Exfiltrate Module
Data extraction capabilities:
- Sensitive data pattern matching
- File type-based extraction
- Data compression and encryption
- Covert exfiltration methods
- Transfer protocols: HTTP(S), SMB, DNS, custom
- Exfiltration size and rate limiting

### C2 Communication Module
Command and control framework:
- Multiple protocol support (HTTP, Socket, Socket.IO)
- Encrypted communication channels
- Command execution and result retrieval
- Persistence mechanism management
- Session handling and tracking
- Anti-detection techniques

### AI Engine Module
Artificial intelligence capabilities:
- Attack pattern recognition
- Behavior prediction and anomaly detection
- Threat intelligence integration
- Attack path analysis
- Automated recommendations
- Historical attack correlation

## Configuration

Configuration is managed through `config.py` with settings stored in `~/.hos_vortex/`:
- `config.json` - Main configuration file with nested settings
- `api_keys.json` - Securely stored API keys (hashed)
- `logs/` - Log files directory with rotation

### Key Configuration Areas:
- Scan settings (ports, timeouts, techniques)
- Escalation preferences
- Lateral movement protocols
- Exfiltration methods and destinations
- C2 communication parameters
- AI model configuration
- Logging and reporting preferences

## Security and Authorization

### Role-Based Access Control
The authorization system includes predefined roles:
- **admin**: Full system access and user management
- **operator**: Execute penetration testing operations
- **analyst**: View results and generate reports
- **guest**: Limited access to public data

### API Key Authentication
Secure authentication using generated API keys with:
- Cryptographic signing
- Key expiration and rotation
- Usage tracking and auditing
- Secure storage (hashed)

## Logging and Auditing

Comprehensive logging system with:
- Daily log rotation
- Colored console output
- Context-aware logging
- Security event tracking
- Module-specific activity logs
- Network communication logging

## Documentation

Detailed documentation is available in the `docs/` directory:
- **Getting Started**: Installation and basic usage
- **Module Guides**: In-depth documentation for each module
- **API Reference**: Programmatic usage details
- **Security Considerations**: Best practices and safety guidelines
- **Development Guide**: Extending the framework

## Contributing

Contributions to hos_vortex are welcome! Please follow these guidelines:
1. Fork the repository
2. Create a feature branch
3. Submit a pull request with detailed changes
4. Include tests for new functionality

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Disclaimer

**IMPORTANT:** This tool is provided for educational and authorized security testing purposes only. The developers assume no liability and are not responsible for any misuse or damage caused by this tool. Users must comply with all applicable laws and regulations and obtain explicit permission before testing any systems.

By using this software, you agree to:
1. Use it only with proper authorization
2. Conduct testing in compliance with laws
3. Take responsibility for your actions
4. Not use it for malicious purposes