A modern Command and Control (C2) framework designed for authorized security testing, red team exercises, and defensive security research.
THIS FRAMEWORK IS INTENDED FOR AUTHORIZED SECURITY TESTING ONLY
- Use only on systems you own or have explicit written permission to test
- Unauthorized use is illegal and unethical
- Always follow responsible disclosure practices
- Comply with all applicable laws and regulations
- Use for defensive security research and authorized penetration testing only
This framework is designed for:
- Authorized Penetration Testing: Simulate real-world attacks in controlled environments
- Red Team Exercises: Test organizational security posture and incident response
- Security Research: Study attack patterns and develop defensive strategies
- Training & Education: Learn about C2 techniques in safe, isolated environments
- Blue Team Training: Understand attacker tools to improve detection capabilities
- React-based Dashboard: Clean, responsive UI with real-time updates
- Authentication System: Secure login with role-based access control
- Session Management: Organize and track testing sessions
- Real-time Monitoring: Live agent status and activity feeds
- Multi-platform Support: Windows, Linux, and macOS compatibility
- Multiple Communication Protocols: HTTP/HTTPS, DNS, WebSocket
- Modular Architecture: Easily extensible plugin system
- End-to-end Encryption: Secure communications with strong cryptography
- Comprehensive Logging: Detailed audit trails for compliance
- Anti-detection Techniques: Evasion capabilities for realistic testing
- Sandbox Detection: Identify virtualized environments
- Process Management: Advanced process injection and hollowing
- Network Tools: Port scanning, lateral movement simulation
- Executive Reports: High-level summaries for management
- Technical Reports: Detailed findings with remediation steps
- MITRE ATT&CK Mapping: Align activities with established frameworks
- IOC Generation: Indicators of Compromise for detection teams
Ensure you have the following installed:
- Docker and Docker Compose (recommended)
- Python 3.8+ (for development)
- Node.js 16+ (for development)
- Git (for version control)
-
Clone the repository:
git clone https://github.com/0w15h3115/ClaudeC2.git cd ClaudeC2 -
Configure environment:
cp .env.example .env # Edit .env with your configuration -
Start the services:
docker-compose up -d
-
Access the web interface:
- URL: http://localhost:3000
- Username:
owlshells - Password:
KimPossible2
-
Setup the server:
cd server pip install -r requirements.txt python run.py -
Setup the client:
cd client npm install npm run dev
- Change Default Credentials: Immediately update the default admin password
- Configure SSL/TLS: Enable HTTPS for production deployments
- Review Configuration: Customize settings in
config/server.yaml - Create Test Session: Start your first authorized testing session
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ React Client │────▶│ FastAPI Server │────▶│ PostgreSQL │
│ (Port 3000) │ │ (Port 8000) │ │ (Port 5432) │
└─────────────────┘ └────────┬────────┘ └─────────────────┘
│
┌────────┴────────┐
│ Redis Cache │
│ (Port 6379) │
└────────┬────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
┌────▼────┐ ┌────▼────┐ ┌────▼────┐
│ Agent 1 │ │ Agent 2 │ │ Agent N │
│ Windows │ │ Linux │ │ macOS │
└─────────┘ └─────────┘ └─────────┘
- Client: React-based web interface with modern UI/UX
- Server: FastAPI backend with RESTful API architecture
- Database: PostgreSQL for persistent data storage
- Cache: Redis for session management and real-time features
- Agents: Cross-platform implants with modular capabilities
- Navigate to the Sessions page
- Click "New Session"
- Configure session parameters:
- Name and description
- Target environment details
- Authorization documentation
- Set up listeners on appropriate ports
- Generate and deploy agents
# Using make commands
make payload-windows # Generate Windows executable
make payload-linux # Generate Linux payload
make payload-macos # Generate macOS payload
# Or use the web UI payload generator for custom options- Command Execution: Run commands remotely
- File Operations: Upload, download, and manage files
- Process Management: List, create, and terminate processes
- Network Tools: Port scans, network discovery
- Screenshot Capture: Visual reconnaissance
Configure listeners for different protocols:
listeners:
http:
port: 8080
ssl: false
https:
port: 8443
ssl: true
cert_file: "/path/to/cert.pem"
key_file: "/path/to/key.pem"
dns:
port: 53
domain: "example.com"ClaudeC2/
├── server/ # Backend API server
│ ├── api/ # REST API endpoints
│ ├── core/ # Core functionality
│ ├── listeners/ # Protocol listeners
│ └── services/ # Business logic
├── client/ # React frontend
│ ├── src/
│ │ ├── components/ # React components
│ │ ├── services/ # API clients
│ │ └── contexts/ # State management
├── agent/ # Agent/implant code
│ ├── core/ # Core agent functionality
│ ├── modules/ # Feature modules
│ └── transports/ # Communication protocols
├── shared/ # Shared libraries
├── config/ # Configuration files
├── scripts/ # Utility scripts
├── docs/ # Documentation
└── tests/ # Test suites
-
Backend Development:
cd server pip install -r requirements.txt uvicorn api.main:app --reload -
Frontend Development:
cd client npm install npm run dev -
Running Tests:
# All tests make test # Specific components make test-server make test-client make test-agent
# Build all components
make build
# Individual components
make build-server
make build-client
make build-agentEdit config/server.yaml:
server:
host: "0.0.0.0"
port: 8000
debug: false
database:
url: "postgresql://user:password@localhost:5432/c2db"
pool_size: 10
security:
secret_key: "your-secret-key-here"
token_expire_minutes: 30
password_hash_rounds: 12
logging:
level: "INFO"
file: "/var/log/c2/server.log"Create .env file:
# Database
POSTGRES_USER=c2user
POSTGRES_PASSWORD=secure_password
POSTGRES_DB=c2database
# Security
SECRET_KEY=your-super-secret-jwt-key
ADMIN_PASSWORD=your-admin-password
# Optional
DEBUG=false
LOG_LEVEL=INFO- Change Default Credentials: Update all default passwords immediately
- Use HTTPS: Always enable SSL/TLS in production
- Network Segmentation: Isolate C2 infrastructure from production networks
- Access Control: Implement strong authentication and authorization
- Regular Updates: Keep all components updated with security patches
- Audit Logging: Enable comprehensive logging for all activities
- Session Management: Use proper session timeouts and controls
- Data Encryption: Ensure all communications are encrypted
- Secure Storage: Protect configuration files and certificates
- Incident Response: Have procedures for security incidents
We welcome contributions from the security community!
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Follow existing code style and conventions
- Add tests for new functionality
- Update documentation as needed
- Ensure all tests pass before submitting
- Include clear commit messages
When reporting bugs, please include:
- Operating system and version
- Python/Node.js versions
- Steps to reproduce the issue
- Expected vs actual behavior
- Log files and error messages
- API Documentation - Complete API reference
- Agent Development - Building custom agents
- Deployment Guide - Production deployment
- Contributing Guide - Development guidelines
- Troubleshooting - Common issues and solutions
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Security: For security issues, please email security@example.com
This project is licensed under the MIT License - see the LICENSE file for details.
IMPORTANT: This tool is provided for educational and authorized testing purposes only.
- The authors are not responsible for any misuse or damage caused by this software
- Users are solely responsible for ensuring they have proper authorization before use
- This tool should only be used in compliance with applicable laws and regulations
- Use of this tool against systems without explicit permission is illegal
- Always follow responsible disclosure practices when conducting security research
- Security researchers and ethical hackers who contribute to making systems safer
- The open-source community for providing foundational tools and libraries
- Organizations that support security research and responsible disclosure
- Red and blue team professionals who help test and improve security postures
Remember: With great power comes great responsibility. Use this tool ethically and legally.