Initial commit: Werkzeuge-Sammlung
Enthält: - rdp_client.py: RDP Client mit GUI und Monitor-Auswahl - rdp.sh: Bash-basierter RDP Client - teamleader_test/: Network Scanner Fullstack-App - teamleader_test2/: Network Mapper CLI Subdirectories mit eigenem Repo wurden ausgeschlossen. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
root
446
teamleader_test/README.md
Normal file
446
teamleader_test/README.md
Normal file
@@ -0,0 +1,446 @@
|
||||
# Network Scanner & Visualization Tool
|
||||
|
||||
A comprehensive network scanning and visualization tool built with FastAPI, React, and Docker. Discover hosts, detect services, and visualize network topology with interactive diagrams.
|
||||
|
||||
**Status**: ✅ Production Ready | **Version**: 1.0.0 | **Last Updated**: December 4, 2025
|
||||
|
||||
---
|
||||
|
||||
## 📚 Documentation
|
||||
|
||||
**→ [Full Documentation Index](docs/index.md)** ← Start here for complete documentation
|
||||
|
||||
### Quick Links
|
||||
|
||||
- **[Quick Start Guide](QUICKSTART.md)** - Get running in 5 minutes
|
||||
- **[Docker Setup](docs/setup/docker.md)** - Container deployment
|
||||
- **[Troubleshooting](docs/guides/troubleshooting.md)** - Common issues & solutions
|
||||
- **[Contributing](CONTRIBUTING.md)** - Development workflow
|
||||
- **[Project Status](docs/project-status.md)** - Feature completeness
|
||||
- **[Architecture](docs/architecture/overview.md)** - Design decisions
|
||||
|
||||
**For AI Agents**: Read [.github/copilot-instructions.md](.github/copilot-instructions.md) for critical patterns and mandatory documentation workflows.
|
||||
|
||||
---
|
||||
|
||||
## Features
|
||||
|
||||
- **Network Host Discovery**: Scan networks to discover active hosts
|
||||
- **Port Scanning**: Detect open ports and running services
|
||||
- **Service Detection**: Identify service types and versions
|
||||
- **Network Topology**: Generate network topology graphs
|
||||
- **Real-time Updates**: WebSocket support for live scan progress
|
||||
- **REST API**: Complete RESTful API for all operations
|
||||
- **No Root Required**: Socket-based scanning works without root privileges
|
||||
- **Optional Nmap Integration**: Use nmap for advanced scanning capabilities
|
||||
|
||||
## Architecture
|
||||
|
||||
### Technology Stack
|
||||
|
||||
- **Backend Framework**: FastAPI (async Python web framework)
|
||||
- **Database**: SQLite with SQLAlchemy ORM
|
||||
- **Network Scanning**:
|
||||
- Socket-based TCP connect scanning (no root)
|
||||
- python-nmap integration (optional)
|
||||
- Custom service detection and banner grabbing
|
||||
- **Real-time Communication**: WebSockets
|
||||
|
||||
### Project Structure
|
||||
|
||||
```
|
||||
teamleader_test/
|
||||
├── app/
|
||||
│ ├── __init__.py
|
||||
│ ├── config.py # Configuration management
|
||||
│ ├── database.py # Database setup
|
||||
│ ├── models.py # SQLAlchemy models
|
||||
│ ├── schemas.py # Pydantic schemas
|
||||
│ ├── api/
|
||||
│ │ ├── __init__.py
|
||||
│ │ └── endpoints/
|
||||
│ │ ├── scans.py # Scan endpoints
|
||||
│ │ ├── hosts.py # Host endpoints
|
||||
│ │ ├── topology.py # Topology endpoints
|
||||
│ │ └── websocket.py # WebSocket endpoint
|
||||
│ ├── scanner/
|
||||
│ │ ├── __init__.py
|
||||
│ │ ├── network_scanner.py # Host discovery
|
||||
│ │ ├── port_scanner.py # Port scanning
|
||||
│ │ ├── service_detector.py# Service detection
|
||||
│ │ └── nmap_scanner.py # Nmap integration
|
||||
│ └── services/
|
||||
│ ├── __init__.py
|
||||
│ ├── scan_service.py # Scan orchestration
|
||||
│ └── topology_service.py# Topology generation
|
||||
├── main.py # Application entry point
|
||||
├── requirements.txt # Python dependencies
|
||||
├── .env.example # Example environment variables
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
## Installation
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Python 3.10 or higher
|
||||
- pip (Python package manager)
|
||||
- Optional: nmap installed on system for advanced scanning
|
||||
|
||||
### Setup
|
||||
|
||||
1. **Clone or navigate to the project directory**:
|
||||
```bash
|
||||
cd /home/rwiegand/Nextcloud/entwicklung/Werkzeuge/teamleader_test
|
||||
```
|
||||
|
||||
2. **Create a virtual environment**:
|
||||
```bash
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate # On Windows: venv\Scripts\activate
|
||||
```
|
||||
|
||||
3. **Install dependencies**:
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
4. **Configure environment variables**:
|
||||
```bash
|
||||
cp .env.example .env
|
||||
# Edit .env with your settings
|
||||
```
|
||||
|
||||
5. **Initialize the database** (happens automatically on first run):
|
||||
```bash
|
||||
python main.py
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Running the Server
|
||||
|
||||
**Development mode** (with auto-reload):
|
||||
```bash
|
||||
python main.py
|
||||
```
|
||||
|
||||
**Production mode** with uvicorn:
|
||||
```bash
|
||||
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4
|
||||
```
|
||||
|
||||
The API will be available at:
|
||||
- API: http://localhost:8000
|
||||
- Interactive Docs: http://localhost:8000/docs
|
||||
- ReDoc: http://localhost:8000/redoc
|
||||
|
||||
### API Endpoints
|
||||
|
||||
#### Scan Operations
|
||||
|
||||
**Start a new scan**:
|
||||
```bash
|
||||
POST /api/scans/start
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"network_range": "192.168.1.0/24",
|
||||
"scan_type": "quick",
|
||||
"port_range": null,
|
||||
"include_service_detection": true,
|
||||
"use_nmap": false
|
||||
}
|
||||
```
|
||||
|
||||
**Get scan status**:
|
||||
```bash
|
||||
GET /api/scans/{scan_id}/status
|
||||
```
|
||||
|
||||
**List all scans**:
|
||||
```bash
|
||||
GET /api/scans?limit=50&offset=0
|
||||
```
|
||||
|
||||
**Cancel a scan**:
|
||||
```bash
|
||||
DELETE /api/scans/{scan_id}/cancel
|
||||
```
|
||||
|
||||
#### Host Operations
|
||||
|
||||
**List discovered hosts**:
|
||||
```bash
|
||||
GET /api/hosts?status=online&limit=100&offset=0
|
||||
```
|
||||
|
||||
**Get host details**:
|
||||
```bash
|
||||
GET /api/hosts/{host_id}
|
||||
```
|
||||
|
||||
**Get host by IP**:
|
||||
```bash
|
||||
GET /api/hosts/ip/{ip_address}
|
||||
```
|
||||
|
||||
**Get host services**:
|
||||
```bash
|
||||
GET /api/hosts/{host_id}/services
|
||||
```
|
||||
|
||||
**Get network statistics**:
|
||||
```bash
|
||||
GET /api/hosts/statistics
|
||||
```
|
||||
|
||||
#### Topology Operations
|
||||
|
||||
**Get network topology**:
|
||||
```bash
|
||||
GET /api/topology?include_offline=false
|
||||
```
|
||||
|
||||
**Get host neighbors**:
|
||||
```bash
|
||||
GET /api/topology/neighbors/{host_id}
|
||||
```
|
||||
|
||||
#### WebSocket
|
||||
|
||||
**Connect to WebSocket for real-time updates**:
|
||||
```javascript
|
||||
const ws = new WebSocket('ws://localhost:8000/api/ws');
|
||||
|
||||
ws.onmessage = (event) => {
|
||||
const message = JSON.parse(event.data);
|
||||
console.log('Received:', message);
|
||||
};
|
||||
|
||||
// Subscribe to scan updates
|
||||
ws.send(JSON.stringify({
|
||||
type: 'subscribe',
|
||||
scan_id: 1
|
||||
}));
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
Edit `.env` file or set environment variables:
|
||||
|
||||
```bash
|
||||
# Database
|
||||
DATABASE_URL=sqlite:///./network_scanner.db
|
||||
|
||||
# Application
|
||||
APP_NAME=Network Scanner
|
||||
DEBUG=False
|
||||
|
||||
# Scanning
|
||||
DEFAULT_SCAN_TIMEOUT=3
|
||||
MAX_CONCURRENT_SCANS=50
|
||||
ENABLE_NMAP=True
|
||||
|
||||
# Network
|
||||
DEFAULT_NETWORK_RANGE=192.168.1.0/24
|
||||
SCAN_PRIVATE_NETWORKS_ONLY=True
|
||||
|
||||
# API
|
||||
API_PREFIX=/api
|
||||
CORS_ORIGINS=["http://localhost:3000"]
|
||||
|
||||
# Logging
|
||||
LOG_LEVEL=INFO
|
||||
LOG_FILE=logs/network_scanner.log
|
||||
```
|
||||
|
||||
## Scan Types
|
||||
|
||||
### Quick Scan
|
||||
- Scans top 15 most common ports
|
||||
- Fast execution (~30 seconds for /24 network)
|
||||
- Suitable for quick network discovery
|
||||
|
||||
### Standard Scan
|
||||
- Scans top 1000 ports
|
||||
- Balanced speed and coverage (~2-3 minutes)
|
||||
- Recommended for most use cases
|
||||
|
||||
### Deep Scan
|
||||
- Scans all 65535 ports
|
||||
- Comprehensive but slow (~15-20 minutes)
|
||||
- Use for thorough security audits
|
||||
|
||||
### Custom Scan
|
||||
- Specify custom port ranges
|
||||
- Example: "80,443,8000-8100"
|
||||
- Flexible for specific needs
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Network Scanning Ethics
|
||||
- **Only scan networks you own or have explicit permission to scan**
|
||||
- Tool defaults to private network ranges only
|
||||
- All scanning activity is logged
|
||||
|
||||
### Network Impact
|
||||
- Rate limiting prevents network disruption
|
||||
- Configurable timeout and concurrency settings
|
||||
- Respectful scanning practices
|
||||
|
||||
### Application Security
|
||||
- Input validation on all endpoints
|
||||
- Network range validation (private networks only by default)
|
||||
- No command injection vulnerabilities
|
||||
- SQL injection protection via SQLAlchemy
|
||||
|
||||
## Development
|
||||
|
||||
### Running Tests
|
||||
```bash
|
||||
pytest tests/
|
||||
```
|
||||
|
||||
### Code Style
|
||||
```bash
|
||||
# Format code
|
||||
black app/
|
||||
|
||||
# Lint
|
||||
pylint app/
|
||||
flake8 app/
|
||||
```
|
||||
|
||||
### Database Migrations
|
||||
```bash
|
||||
# Create migration
|
||||
alembic revision --autogenerate -m "description"
|
||||
|
||||
# Apply migrations
|
||||
alembic upgrade head
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Port Scanning Issues
|
||||
|
||||
**Problem**: No hosts discovered
|
||||
- Check network range is correct
|
||||
- Ensure hosts are actually online (try pinging them)
|
||||
- Firewall might be blocking scans
|
||||
|
||||
**Problem**: Slow scanning
|
||||
- Reduce `MAX_CONCURRENT_SCANS` in config
|
||||
- Use "quick" scan type instead of "deep"
|
||||
- Check network latency
|
||||
|
||||
### Nmap Issues
|
||||
|
||||
**Problem**: Nmap not working
|
||||
- Install nmap: `sudo apt-get install nmap` (Linux) or `brew install nmap` (macOS)
|
||||
- Set `use_nmap: false` in scan config to use socket-based scanning
|
||||
- Check nmap is in PATH
|
||||
|
||||
### Database Issues
|
||||
|
||||
**Problem**: Database locked
|
||||
- Only one process can write to SQLite at a time
|
||||
- Close other connections to the database
|
||||
- Consider using PostgreSQL for multi-user scenarios
|
||||
|
||||
## Performance
|
||||
|
||||
### Benchmarks
|
||||
- Quick scan (/24 network): ~30 seconds
|
||||
- Standard scan (/24 network): ~2-3 minutes
|
||||
- Deep scan (single host): ~15-20 minutes
|
||||
|
||||
### Optimization Tips
|
||||
- Use socket-based scanning for speed (no nmap)
|
||||
- Increase `MAX_CONCURRENT_SCANS` for faster execution
|
||||
- Reduce `DEFAULT_SCAN_TIMEOUT` for quicker host checks
|
||||
- Disable service detection for faster scans
|
||||
|
||||
## API Examples
|
||||
|
||||
### Python Client Example
|
||||
|
||||
```python
|
||||
import requests
|
||||
|
||||
# Start a scan
|
||||
response = requests.post('http://localhost:8000/api/scans/start', json={
|
||||
'network_range': '192.168.1.0/24',
|
||||
'scan_type': 'quick'
|
||||
})
|
||||
scan_id = response.json()['scan_id']
|
||||
|
||||
# Check status
|
||||
status = requests.get(f'http://localhost:8000/api/scans/{scan_id}/status')
|
||||
print(status.json())
|
||||
|
||||
# Get topology
|
||||
topology = requests.get('http://localhost:8000/api/topology')
|
||||
print(topology.json())
|
||||
```
|
||||
|
||||
### JavaScript Client Example
|
||||
|
||||
```javascript
|
||||
// Start a scan
|
||||
const startScan = async () => {
|
||||
const response = await fetch('http://localhost:8000/api/scans/start', {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({
|
||||
network_range: '192.168.1.0/24',
|
||||
scan_type: 'quick'
|
||||
})
|
||||
});
|
||||
const data = await response.json();
|
||||
return data.scan_id;
|
||||
};
|
||||
|
||||
// Get hosts
|
||||
const getHosts = async () => {
|
||||
const response = await fetch('http://localhost:8000/api/hosts');
|
||||
return await response.json();
|
||||
};
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
This project is provided as-is for educational and authorized network administration purposes only.
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions:
|
||||
1. Check the troubleshooting section
|
||||
2. Review API documentation at `/docs`
|
||||
3. Check application logs in `logs/network_scanner.log`
|
||||
|
||||
## Roadmap
|
||||
|
||||
### Future Enhancements
|
||||
- [ ] Vulnerability scanning integration
|
||||
- [ ] Network change detection and alerting
|
||||
- [ ] Historical trend analysis
|
||||
- [ ] Scheduled scanning
|
||||
- [ ] Export to PDF/PNG
|
||||
- [ ] Multi-subnet support
|
||||
- [ ] PostgreSQL support for larger deployments
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions are welcome! Please ensure:
|
||||
- Code follows PEP 8 style guidelines
|
||||
- All tests pass
|
||||
- New features include tests
|
||||
- Documentation is updated
|
||||
|
||||
---
|
||||
|
||||
**Author**: DevAgent
|
||||
**Version**: 1.0.0
|
||||
**Last Updated**: December 4, 2025
|
||||
Reference in New Issue
Block a user