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
467
teamleader_test/docs/setup/local-development.md
Normal file
467
teamleader_test/docs/setup/local-development.md
Normal file
@@ -0,0 +1,467 @@
|
||||
# Network Scanner - Full Stack Quick Start Guide
|
||||
|
||||
This guide helps you get both backend and frontend running together.
|
||||
|
||||
## 🚀 Quick Start (5 minutes)
|
||||
|
||||
### Step 1: Start Backend
|
||||
|
||||
```bash
|
||||
# From project root
|
||||
cd /home/rwiegand/Nextcloud/entwicklung/Werkzeuge/teamleader_test
|
||||
|
||||
# Start backend server
|
||||
./start.sh
|
||||
# OR
|
||||
python main.py
|
||||
```
|
||||
|
||||
The backend will be available at: `http://localhost:8000`
|
||||
|
||||
### Step 2: Install Frontend Dependencies
|
||||
|
||||
```bash
|
||||
# Open new terminal
|
||||
cd /home/rwiegand/Nextcloud/entwicklung/Werkzeuge/teamleader_test/frontend
|
||||
|
||||
# Run setup
|
||||
./setup.sh
|
||||
# OR
|
||||
npm install
|
||||
```
|
||||
|
||||
### Step 3: Start Frontend
|
||||
|
||||
```bash
|
||||
# From frontend directory
|
||||
./start.sh
|
||||
# OR
|
||||
npm run dev
|
||||
```
|
||||
|
||||
The frontend will be available at: `http://localhost:3000`
|
||||
|
||||
### Step 4: Use the Application
|
||||
|
||||
1. Open browser to `http://localhost:3000`
|
||||
2. You'll see the Dashboard
|
||||
3. Enter a network range (e.g., `192.168.1.0/24`)
|
||||
4. Click "Start Scan"
|
||||
5. Watch real-time progress
|
||||
6. Explore the Network Map, Hosts, and Scans pages
|
||||
|
||||
## 📊 Architecture Overview
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ USER BROWSER │
|
||||
│ http://localhost:3000 │
|
||||
└─────────────────────┬───────────────────────────────────────┘
|
||||
│
|
||||
│ HTTP/WebSocket
|
||||
│
|
||||
┌─────────────────────▼───────────────────────────────────────┐
|
||||
│ VITE DEV SERVER (3000) │
|
||||
│ ┌────────────────────────────────────────────────────┐ │
|
||||
│ │ React TypeScript Frontend │ │
|
||||
│ │ • Dashboard • Network Map • Hosts • Scans │ │
|
||||
│ └────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ Proxy: /api/* → http://localhost:8000/api/* │
|
||||
└─────────────────────┬───────────────────────────────────────┘
|
||||
│
|
||||
│ REST API + WebSocket
|
||||
│
|
||||
┌─────────────────────▼───────────────────────────────────────┐
|
||||
│ FASTAPI BACKEND (8000) │
|
||||
│ ┌────────────────────────────────────────────────────┐ │
|
||||
│ │ REST API Endpoints │ │
|
||||
│ │ • /api/scans/* • /api/hosts/* • /api/topology/* │ │
|
||||
│ └────────────────────────────────────────────────────┘ │
|
||||
│ ┌────────────────────────────────────────────────────┐ │
|
||||
│ │ WebSocket Endpoint │ │
|
||||
│ │ • /api/ws (real-time updates) │ │
|
||||
│ └────────────────────────────────────────────────────┘ │
|
||||
│ ┌────────────────────────────────────────────────────┐ │
|
||||
│ │ Network Scanner Engine │ │
|
||||
│ │ • Port scanning • Service detection │ │
|
||||
│ │ • Topology analysis • Database storage │ │
|
||||
│ └────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ Database: SQLite (scanner.db) │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## 🔌 API Integration Details
|
||||
|
||||
### REST API Flow
|
||||
|
||||
```
|
||||
Frontend Component
|
||||
↓
|
||||
Custom Hook (useHosts, useScans, etc.)
|
||||
↓
|
||||
API Service (services/api.ts)
|
||||
↓
|
||||
Axios HTTP Request
|
||||
↓
|
||||
Vite Dev Proxy (/api → :8000/api)
|
||||
↓
|
||||
FastAPI Backend
|
||||
↓
|
||||
Database / Scanner
|
||||
↓
|
||||
JSON Response
|
||||
↓
|
||||
React State Update
|
||||
↓
|
||||
UI Re-render
|
||||
```
|
||||
|
||||
### WebSocket Flow
|
||||
|
||||
```
|
||||
Frontend App Start
|
||||
↓
|
||||
useWebSocket Hook
|
||||
↓
|
||||
WebSocket Client (services/websocket.ts)
|
||||
↓
|
||||
WS Connection: ws://localhost:8000/api/ws
|
||||
↓
|
||||
Backend WebSocket Manager
|
||||
↓
|
||||
Scan Events (progress, complete, host_discovered)
|
||||
↓
|
||||
Message Handler in Hook
|
||||
↓
|
||||
State Update
|
||||
↓
|
||||
UI Re-render (real-time)
|
||||
```
|
||||
|
||||
## 🧪 Testing the Integration
|
||||
|
||||
### 1. Test Backend Alone
|
||||
|
||||
```bash
|
||||
# Check health
|
||||
curl http://localhost:8000/health
|
||||
|
||||
# List hosts
|
||||
curl http://localhost:8000/api/hosts
|
||||
|
||||
# Start scan (from CLI)
|
||||
python cli.py scan 127.0.0.1
|
||||
```
|
||||
|
||||
### 2. Test Frontend-Backend Integration
|
||||
|
||||
1. **Start both servers**
|
||||
2. **Open browser console** (F12)
|
||||
3. **Go to Network tab**
|
||||
4. **Trigger actions and verify**:
|
||||
- API calls show in Network tab
|
||||
- WebSocket connection established
|
||||
- Real-time updates received
|
||||
|
||||
### 3. Test WebSocket
|
||||
|
||||
1. Start a scan from frontend
|
||||
2. Open browser console
|
||||
3. Watch for WebSocket messages:
|
||||
```javascript
|
||||
// You should see:
|
||||
{ type: 'scan_progress', data: { ... } }
|
||||
{ type: 'host_discovered', data: { ... } }
|
||||
{ type: 'scan_complete', data: { ... } }
|
||||
```
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
### Backend Issues
|
||||
|
||||
**Port 8000 already in use**
|
||||
```bash
|
||||
# Find process
|
||||
lsof -i :8000
|
||||
# Kill it
|
||||
kill -9 <PID>
|
||||
```
|
||||
|
||||
**Permission denied (for nmap)**
|
||||
```bash
|
||||
# Run without nmap or with sudo
|
||||
python main.py
|
||||
```
|
||||
|
||||
**Database locked**
|
||||
```bash
|
||||
# Stop all backend instances
|
||||
pkill -f "python main.py"
|
||||
# Remove lock
|
||||
rm scanner.db-journal
|
||||
```
|
||||
|
||||
### Frontend Issues
|
||||
|
||||
**Port 3000 already in use**
|
||||
```bash
|
||||
# Vite will automatically try 3001, 3002, etc.
|
||||
# Or kill the process:
|
||||
lsof -i :3000
|
||||
kill -9 <PID>
|
||||
```
|
||||
|
||||
**Cannot connect to backend**
|
||||
- Verify backend is running: `curl http://localhost:8000/health`
|
||||
- Check `.env` file has correct URLs
|
||||
- Check browser console for CORS errors
|
||||
|
||||
**WebSocket not connecting**
|
||||
- Backend CORS must allow WebSocket
|
||||
- Check WebSocket URL in `.env`
|
||||
- Backend must support WebSocket upgrade
|
||||
|
||||
### Integration Issues
|
||||
|
||||
**CORS Errors**
|
||||
|
||||
Backend should have:
|
||||
```python
|
||||
app.add_middleware(
|
||||
CORSMiddleware,
|
||||
allow_origins=["http://localhost:3000"],
|
||||
allow_credentials=True,
|
||||
allow_methods=["*"],
|
||||
allow_headers=["*"],
|
||||
)
|
||||
```
|
||||
|
||||
**Proxy Not Working**
|
||||
|
||||
Check `frontend/vite.config.ts`:
|
||||
```typescript
|
||||
proxy: {
|
||||
'/api': {
|
||||
target: 'http://localhost:8000',
|
||||
changeOrigin: true,
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## 📝 Development Workflow
|
||||
|
||||
### Typical Development Session
|
||||
|
||||
```bash
|
||||
# Terminal 1: Backend
|
||||
cd ~/Nextcloud/entwicklung/Werkzeuge/teamleader_test
|
||||
python main.py
|
||||
|
||||
# Terminal 2: Frontend
|
||||
cd ~/Nextcloud/entwicklung/Werkzeuge/teamleader_test/frontend
|
||||
npm run dev
|
||||
|
||||
# Terminal 3: Testing
|
||||
cd ~/Nextcloud/entwicklung/Werkzeuge/teamleader_test
|
||||
python cli.py scan 192.168.1.0/24
|
||||
```
|
||||
|
||||
### Making Changes
|
||||
|
||||
**Backend Changes**
|
||||
1. Edit Python files
|
||||
2. Backend auto-reloads (if uvicorn reload enabled)
|
||||
3. Frontend automatically uses new API
|
||||
|
||||
**Frontend Changes**
|
||||
1. Edit React/TypeScript files
|
||||
2. Vite hot-reloads automatically
|
||||
3. Browser updates instantly
|
||||
|
||||
## 🚢 Production Deployment
|
||||
|
||||
### Backend
|
||||
|
||||
```bash
|
||||
# Option 1: Direct
|
||||
uvicorn app.main:app --host 0.0.0.0 --port 8000
|
||||
|
||||
# Option 2: Gunicorn
|
||||
gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker
|
||||
|
||||
# Option 3: Docker
|
||||
docker build -t network-scanner-backend .
|
||||
docker run -p 8000:8000 network-scanner-backend
|
||||
```
|
||||
|
||||
### Frontend
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm run build
|
||||
|
||||
# Output in: frontend/dist/
|
||||
```
|
||||
|
||||
Deploy `dist/` to:
|
||||
- Nginx
|
||||
- Apache
|
||||
- Netlify
|
||||
- Vercel
|
||||
- AWS S3 + CloudFront
|
||||
|
||||
### Full Stack (Docker Compose)
|
||||
|
||||
Create `docker-compose.yml`:
|
||||
```yaml
|
||||
version: '3.8'
|
||||
services:
|
||||
backend:
|
||||
build: .
|
||||
ports:
|
||||
- "8000:8000"
|
||||
volumes:
|
||||
- ./data:/app/data
|
||||
|
||||
frontend:
|
||||
build: ./frontend
|
||||
ports:
|
||||
- "80:80"
|
||||
depends_on:
|
||||
- backend
|
||||
environment:
|
||||
- VITE_API_URL=http://localhost:8000
|
||||
- VITE_WS_URL=ws://localhost:8000
|
||||
```
|
||||
|
||||
Run:
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
## 🔒 Security Considerations
|
||||
|
||||
### Development
|
||||
|
||||
- Backend and frontend on localhost only
|
||||
- CORS restricted to localhost:3000
|
||||
- No authentication (internal use)
|
||||
|
||||
### Production
|
||||
|
||||
Must add:
|
||||
1. **Authentication**: JWT, OAuth, or API keys
|
||||
2. **HTTPS**: TLS certificates required
|
||||
3. **CORS**: Restrict to production domain
|
||||
4. **Rate Limiting**: Prevent abuse
|
||||
5. **Input Validation**: Already implemented
|
||||
6. **Network Scanning**: Ensure authorized networks only
|
||||
|
||||
## 📊 Monitoring
|
||||
|
||||
### Backend Logs
|
||||
|
||||
```bash
|
||||
# Follow logs
|
||||
tail -f logs/network_scanner.log
|
||||
|
||||
# Check for errors
|
||||
grep ERROR logs/network_scanner.log
|
||||
```
|
||||
|
||||
### Frontend Logs
|
||||
|
||||
- Browser console (F12)
|
||||
- Network tab for API calls
|
||||
- React DevTools for component inspection
|
||||
|
||||
## 🎯 Common Use Cases
|
||||
|
||||
### 1. Scan Local Network
|
||||
|
||||
```
|
||||
1. Go to Dashboard
|
||||
2. Enter: 192.168.1.0/24
|
||||
3. Select: Quick scan
|
||||
4. Click: Start Scan
|
||||
5. Monitor progress
|
||||
6. View results in Network Map
|
||||
```
|
||||
|
||||
### 2. Investigate Specific Host
|
||||
|
||||
```
|
||||
1. Go to Hosts page
|
||||
2. Search for IP or hostname
|
||||
3. Click on host
|
||||
4. View services and details
|
||||
5. Check last seen time
|
||||
```
|
||||
|
||||
### 3. Monitor Scan Progress
|
||||
|
||||
```
|
||||
1. Start scan from Dashboard
|
||||
2. Go to Scans page
|
||||
3. Watch real-time progress bar
|
||||
4. View hosts scanned count
|
||||
5. Cancel if needed
|
||||
```
|
||||
|
||||
### 4. Explore Network Topology
|
||||
|
||||
```
|
||||
1. Complete at least one scan
|
||||
2. Go to Network Map
|
||||
3. Pan/zoom to explore
|
||||
4. Click nodes for details
|
||||
5. Observe connections
|
||||
```
|
||||
|
||||
## 📚 Additional Resources
|
||||
|
||||
### Backend Documentation
|
||||
- [README.md](../README.md)
|
||||
- [QUICKSTART.md](../QUICKSTART.md)
|
||||
- [ARCHITECTURE.md](../ARCHITECTURE.md)
|
||||
|
||||
### Frontend Documentation
|
||||
- [README.md](./README.md)
|
||||
- [DEVELOPMENT.md](./DEVELOPMENT.md)
|
||||
- [FRONTEND_SUMMARY.md](./FRONTEND_SUMMARY.md)
|
||||
|
||||
### API Documentation
|
||||
- Swagger UI: http://localhost:8000/docs
|
||||
- ReDoc: http://localhost:8000/redoc
|
||||
|
||||
## ✅ Verification Checklist
|
||||
|
||||
After setup, verify:
|
||||
|
||||
- [ ] Backend running on port 8000
|
||||
- [ ] Frontend running on port 3000
|
||||
- [ ] Can access http://localhost:3000
|
||||
- [ ] Dashboard loads successfully
|
||||
- [ ] Can start a scan
|
||||
- [ ] Real-time updates working
|
||||
- [ ] Network map displays
|
||||
- [ ] Hosts table populated
|
||||
- [ ] WebSocket connected (check console)
|
||||
- [ ] No errors in browser console
|
||||
- [ ] No errors in backend logs
|
||||
|
||||
## 🎉 You're Ready!
|
||||
|
||||
Both backend and frontend are now running and integrated. Start scanning your network!
|
||||
|
||||
---
|
||||
|
||||
**Need Help?**
|
||||
- Check browser console for frontend errors
|
||||
- Check `logs/network_scanner.log` for backend errors
|
||||
- Ensure both servers are running
|
||||
- Verify network connectivity
|
||||
|
||||
**Happy Scanning! 🔍**
|
||||
Reference in New Issue
Block a user