Network reconnaissance and asset discovery tool built with Go and React.
Reconya discovers and monitors devices on your network with real-time updates. Suitable for network administrators, security professionals, and home users.
- Network scanning with nmap integration
- Device identification (MAC addresses, vendor detection, hostnames)
- Real-time monitoring and event logging
- Web-based dashboard
- Device fingerprinting
- Docker and Docker Compose
- Python 3.9+ (for docker-compose compatibility)
If using Python 3.12, you may encounter docker-compose issues. Solutions:
Option 1: Use Docker Compose V2 (recommended)
docker compose version # verify V2 installation
docker compose up -d # note: no hyphenOption 2: Legacy docker-compose
pip install docker-compose # requires Python 3.11 or earlier
# or
pipx install docker-compose-
Clone and setup:
git clone https://github.com/Dyneteq/reconya-ai-go.git cd reconya-ai-go ./setup.sh -
Access at
http://localhost:3001
-
Configure environment:
cp .env.example .env # edit .env with your settings -
Start containers:
# Standard setup (bridge networking) docker compose up -d # OR for full host network access (solves Docker IP detection issues) docker compose -f docker-compose.yml -f docker-compose.host.yml up -d
- Login with credentials from your
.envfile - Configure network range in settings
- Run discovery to scan your network
- Monitor devices in the dashboard
cd backend
cp .env.example .env
go mod download
go run cmd/main.gocd frontend
npm install
npm startFor MAC address detection, install nmap:
# macOS
brew install nmap
# Ubuntu/Debian
sudo apt-get install nmapGrant nmap privileges:
sudo chown root:admin $(which nmap)
sudo chmod u+s $(which nmap)Python 3.12 errors
- Error:
ModuleNotFoundError: No module named 'distutils.spawn' - Solution: Use
docker composeinstead ofdocker-compose
App not accessible
- Check ports 3001 and 3008 aren't in use
- Verify containers are running:
docker ps - Check logs:
./logs.sh
Missing MAC addresses
- Ensure nmap is installed and has proper permissions
- MAC addresses only visible on same network segment
CORS issues
- Check CORS config in
backend/middleware/cors.go - Verify API routing in nginx.conf
Docker IP detection issues
- Error: Reconya detects Docker internal IP instead of host network
- Solution 1: Set correct network range in
.env:NETWORK_RANGE=192.168.1.0/24 # Replace with your actual network - Solution 2: Use host networking for full network access:
docker compose -f docker-compose.yml -f docker-compose.host.yml up -d
- Solution 3: Enable network capabilities (already enabled by default):
cap_add: - NET_ADMIN - NET_RAW
- Backend: Go API with SQLite database
- Frontend: React/TypeScript with Bootstrap
- Scanning: Multi-strategy network discovery with nmap integration
- Deployment: Docker Compose
Reconya uses a multi-layered scanning approach that combines nmap integration with native Go implementations:
1. Network Discovery (Every 30 seconds)
- Multiple nmap strategies with automatic fallback
- ICMP ping sweeps (privileged mode)
- TCP connect probes to common ports (fallback)
- ARP table lookups for MAC address resolution
2. Device Identification
- IEEE OUI database for vendor identification
- Multi-method hostname resolution (DNS, NetBIOS, mDNS)
- Operating system fingerprinting via nmap
- Device type classification based on ports and vendors
3. Port Scanning (Background workers)
- Top 100 ports scan for active services
- Service detection and banner grabbing
- Concurrent scanning with worker pool pattern
4. Web Service Detection
- Automatic discovery of HTTP/HTTPS services
- Screenshot capture using headless Chrome
- Service metadata extraction (titles, server headers)
The system attempts these nmap commands in order:
# Primary: Privileged ICMP scan
sudo nmap -sn --send-ip -T4 -R --system-dns -oX - <network>
# Fallback 1: Unprivileged ICMP
nmap -sn --send-ip -T4 -oX - <network>
# Fallback 2: ARP scan
nmap -sn -PR -T4 -R --system-dns -oX - <network>
# Fallback 3: TCP SYN probe
nmap -sn -PS80,443,22,21,23,25,53,110,111,135,139,143,993,995 -T4 -oX - <network>- 50 concurrent goroutines for network scanning
- 3 background workers for port scanning queue
- Producer-consumer pattern for efficient resource utilization
- Database locking with retry mechanism for data consistency
- Fork the repository
- Create feature branch
- Make changes and test
- Submit pull request
Creative Commons Attribution-NonCommercial 4.0 International License. Commercial use requires permission.
- Tududi - Self-hosted task management with hierarchical organization, multi-language support, and Telegram integration
- BreachHarbor - Cybersecurity suite for digital asset protection
- Hevetra - Digital tracking for child health milestones