cb073786b3
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>
83 lines
4.7 KiB
Markdown
83 lines
4.7 KiB
Markdown
# LAN Graph Explorer - AI Coding Agent Instructions
|
|
|
|
## Project Overview
|
|
Python-based LAN discovery tool that scans local networks via ping/SSH, builds a topology graph, and visualizes it with D3.js. The architecture separates scanning logic ([network_mapper/scanner.py](../network_mapper/scanner.py)), FastAPI backend ([network_mapper/main.py](../network_mapper/main.py)), and D3 frontend ([frontend/](../frontend/)).
|
|
|
|
## Architecture & Data Flow
|
|
1. **Scanner** (`NetworkScanner` class): Auto-discovers primary IPv4 CIDR via `ip -4 addr`, pings all hosts concurrently (default 64), performs reverse DNS lookups, and optionally SSH-probes reachable hosts with `ip neigh show` to discover neighbor relationships
|
|
2. **Data Model**: `HostNode` (IP, DNS, reachability, SSH status), `ConnectionEdge` (source/target IPs + relation type: `gateway`/`neighbor`/`scan`), `ScanResult` (aggregates nodes/edges/metadata)
|
|
3. **API**: FastAPI serves `/api/scan` endpoint accepting `cidr`, `concurrency`, `ssh_timeout` query params; returns JSON graph
|
|
4. **Frontend**: D3 force-directed graph (`d3.forceSimulation`) renders nodes colored by role (gateway=orange, scanner=blue, SSH-enabled=green)
|
|
|
|
## Critical Developer Workflows
|
|
|
|
### Installation & Setup
|
|
```bash
|
|
# Install in virtualenv (project uses Python >=3.11)
|
|
pip install --upgrade pip
|
|
pip install -e . # installs 'lan-graph' CLI from pyproject.toml entry point
|
|
|
|
# For testing
|
|
pip install -e ".[testing]"
|
|
pytest
|
|
```
|
|
|
|
### Running the Tool
|
|
```bash
|
|
# CLI scan (outputs JSON to stdout or --output file)
|
|
lan-graph scan --concurrency 64 --ssh-timeout 5
|
|
|
|
# Start web server (FastAPI + D3 frontend)
|
|
lan-graph serve --host 0.0.0.0 --port 8000
|
|
# Access at http://localhost:8000
|
|
```
|
|
|
|
### SSH Key Authentication
|
|
Set environment variables to enable neighbor discovery via passwordless SSH:
|
|
```bash
|
|
export SSH_USER=team
|
|
export SSH_KEY_PATH=~/.ssh/id_rsa
|
|
```
|
|
Scanner uses `ssh -o BatchMode=yes` to avoid password prompts. CLI flags `--ssh-user` and `--ssh-key` override env vars.
|
|
|
|
## Project-Specific Conventions
|
|
|
|
### Async/Await Patterns
|
|
- **Concurrent scanning**: Uses `asyncio.Semaphore` for rate-limiting ping operations (`_ping_concurrency=64`) and SSH probes (`_ssh_concurrency=10`)
|
|
- **Host probing**: `_probe_host()` acquires semaphore for ping, then conditionally probes SSH; results gathered via `asyncio.gather()`
|
|
- Blocking operations (DNS lookups, subprocess calls) wrapped in `asyncio.to_thread()` or use `asyncio.create_subprocess_exec()`
|
|
|
|
### Edge Deduplication
|
|
In `scanner.py`, edges are deduplicated via `seen_edges` set tracking `(source, target, relation)` tuples before creating `ConnectionEdge` objects. This prevents duplicate links in the visualization.
|
|
|
|
### Frontend-Backend Contract
|
|
- `/api/scan` returns JSON matching `ScanResult.to_dict()` structure
|
|
- Nodes must have `ip` field (used as D3 force layout ID)
|
|
- Frontend expects `edges` array with `source`/`target` as IP strings (D3 converts to node references)
|
|
|
|
### Error Handling
|
|
- Scanner methods (`_discover_network`, `_default_gateway`) raise `RuntimeError` with descriptive messages if system commands fail
|
|
- SSH failures return empty neighbor set + `via_ssh=False`; network discovery continues
|
|
- Frontend displays error messages in `#status` element on API fetch failures
|
|
|
|
## Testing Approach
|
|
Uses pytest with basic unit tests in [tests/test_scanner.py](../tests/test_scanner.py):
|
|
- `parse_neighbor_ips()` regex extraction tested with sample `ip neigh` output
|
|
- `ScanResult.to_dict()` serialization validated
|
|
- No integration tests currently; future tests should mock subprocess calls
|
|
|
|
## Key Files & Extension Points
|
|
- **[network_mapper/scanner.py](../network_mapper/scanner.py)**: `_collect_neighbors()` can be extended for additional probes (e.g., `probe_tcp_port()` helpers for HTTP/SMB)
|
|
- **[frontend/script.js](../frontend/script.js)**: `colorForNode()` and `render()` functions define visualization styling; swap `d3.forceSimulation()` for hierarchical layouts if needed
|
|
- **[pyproject.toml](../pyproject.toml)**: Entry point `lan-graph = "network_mapper.cli:app"` uses Typer for CLI generation
|
|
|
|
## Dependencies & Environment
|
|
- **System requirements**: Linux with `ip`, `ping`, `ssh` commands (no Windows support)
|
|
- **Python deps**: FastAPI, uvicorn[standard], typer (see [pyproject.toml](../pyproject.toml))
|
|
- **Frontend**: Vanilla D3.js v7 (loaded from CDN in [frontend/index.html](../frontend/index.html))
|
|
|
|
## Common Issues
|
|
- **"Unable to determine local IPv4 network"**: Scanner requires non-loopback global-scope IPv4 interface
|
|
- **No neighbor edges**: Verify `SSH_USER`/`SSH_KEY_PATH` are set and target hosts allow key-based auth
|
|
- **FastAPI 404 on static files**: Ensure `FRONTEND_DIR` path resolution in `main.py` points to workspace-relative [frontend/](../frontend/) directory
|