Reconya: Real-Time Network Asset Discovery for Modern Security Teams

高效码农

7 hours ago

Reconya: When Network Reconnaissance Meets Modern Web Technologies — An Open-Source Tool That Makes Asset Discovery Intuitive

What problem does Reconya solve for network administrators and security researchers? It provides a lightweight, real-time visualization of all active devices on your network without requiring complex enterprise platforms or deciphering cryptic command-line output.

In today’s hyper-connected world, even a modest home network can host dozens of devices — from smart speakers and NAS units to IoT sensors and development servers. These assets often exist in a state of “visible yet unknown”: we know they’re connected but lack a unified view to understand what they are, what they’re doing, and whether they belong. Reconya was purpose-built to eliminate this modern network blind spot. It’s not a heavyweight network management suite, but a precision instrument focused on reconnaissance and discovery, delivering production-grade capabilities through a developer-friendly technology stack.

What Is Reconya and Why Does It Matter for Modern Networks?

What specific gaps does Reconya fill that traditional tools leave exposed? It bridges the chasm between powerful but opaque command-line scanners like nmap and complex, resource-intensive enterprise platforms like SolarWinds, giving security professionals and advanced home users the perfect balance of depth and usability.

Traditional network tools force you into two extremes: raw terminal output that requires expert interpretation, or bloated management consoles that demand dedicated infrastructure. Reconya finds the sweet spot by answering critical questions instantly: What’s currently on my network? What are its identity credentials? How is its status changing over time? The value isn’t in replacing monitoring systems, but in providing immediate situational awareness.

Application Scenario: Imagine you’re a remote developer with a home lab consisting of a Raspberry Pi cluster, test servers, and various smart home gadgets. One evening your network latency spikes, and you suspect an unauthorized device. Opening Reconya’s dashboard reveals all active devices, their MAC addresses, and vendor information within 30 seconds. An unfamiliar MediaTek device appears — a forgotten smart plug that’s malfunctioning and flooding the network. Without Reconya’s visual summary, you’d be parsing nmap XML output or logging into your router’s clunky interface.

Author Reflection: While testing Reconya in my own environment, I discovered a three-year-old phone that had been automatically reconnecting to Wi-Fi after each factory reset, silently consuming bandwidth in the background. This taught me that the real value of asset discovery isn’t finding what you know exists, but revealing what you’ve forgotten — and forgotten devices are often the weakest security links.

Core Features in Action: From IPv4 Scanning to IPv6 Passive Surveillance

What concrete capabilities does Reconya offer, and how do they perform under real-world conditions? The tool delivers comprehensive IPv4 discovery, intelligent IPv6 passive monitoring, multi-layered device fingerprinting, and real-time visual feedback through a modern web interface.

IPv4 Network Scanning: More Than Just Ping

How does Reconya’s IPv4 discovery differ from basic ping sweeps? It employs a multi-strategy approach that automatically adapts to execution context, prioritizing ICMP in privileged mode and falling back to TCP probes when necessary, ensuring maximum coverage regardless of runtime constraints.

The scanning engine doesn’t naively ping addresses. It orchestrates nmap with intelligent fallback: privileged ICMP requests first, then TCP SYN packets to high-probability ports like 80, 443, 22, and 445 if raw sockets are unavailable. Simultaneously, it harvests MAC addresses from the system’s ARP table, capturing devices that have communicated recently but might not respond to active probes.

Application Scenario: During a penetration test pre-engagement survey, a tester deployed Reconya inside a client’s containerized infrastructure where privileged mode was restricted. The tool automatically fell back to TCP connect probes, discovering a printer management interface on port 8080 that ignored ICMP entirely. This device would have been invisible to traditional ping sweeps but was critical to the attack surface.

IPv6 Passive Monitoring: Silent Intelligence Gathering

How does Reconya achieve IPv6 device discovery without generating network traffic? It passively monitors the Neighbor Discovery Protocol (NDP) and interface address changes, transforming the kernel’s existing network events into actionable intelligence without sending a single probe packet.

IPv6’s 128-bit address space renders active scanning mathematically infeasible. Reconya’s solution is pure passive observation: it watches the kernel’s neighbor cache for NDP neighbor advertisements (NA) and neighbor solicitations (NS), extracting IPv6-to-MAC mappings in real time. It also tracks interface address assignments, automatically classifying Link-Local (fe80::/10), Unique Local (fc00::/7), and Global (2000::/3) addresses.

Application Scenario: A university network center needed to audit IPv6 deployment across campus buildings. Traditional tools were useless against the massive address space. After deploying Reconya for one week of passive monitoring, they accurately mapped IPv6 device distribution and discovered that hundreds of IoT devices were auto-configuring Global addresses, creating unexpected external exposure points that bypassed IPv4 firewall rules.

Author Reflection: The passive philosophy of IPv6 monitoring reframed my understanding of reconnaissance. The best surveillance is undetectable surveillance. In red-team exercises, active scanning triggers IDS alerts, while passive listening acts like a network microscope — observing without altering. This capability is invaluable for detecting Advanced Persistent Threats (APTs) that deliberately avoid active probes.

Multi-Dimensional Device Fingerprinting

What transforms an IP address into a meaningful asset profile? Reconya builds identity through four layers: hardware vendor via MAC OUI lookup, hostname through multi-protocol resolution, operating system via nmap fingerprinting, and services through port scanning with banner grabbing and web screenshots.

A discovered IP isn’t just a number. Reconya queries the IEEE OUI database to identify manufacturers like “Intel” or “Espressif.” It simultaneously resolves hostnames via reverse DNS, mDNS (Bonjour), and NetBIOS, taking the fastest response. OS detection uses nmap’s signature database, while service discovery scans the top 100 ports, grabbing banners and capturing screenshots of HTTP/HTTPS interfaces using headless Chrome.

Application Scenario: In a home network, Reconya doesn’t just show 192.168.1.105. It reveals: “Raspberry Pi 4 running Raspbian, hostname pi-hole, serving DNS on port 53 and a web interface on port 80, manufacturer Raspberry Pi Foundation, with a screenshot showing the Pi-hole admin login.” This granularity turns a mystery IP into a known asset with a clear purpose.

Installation Reality Check: Why Local Deployment Is the Only Recommended Path

Why does Reconya explicitly label Docker support as experimental while strongly recommending local installation? Docker’s network namespace isolation fundamentally blocks Layer 2 access, preventing reliable MAC address discovery even with privileged mode, making local installation the only way to guarantee full functionality.

The project’s documentation is refreshingly honest: Docker containers cannot reliably access ARP tables or send link-layer frames across segments. While many projects compromise functionality to chase cloud-native trends, Reconya’s maintainers clearly state that full MAC discovery requires a local installation. The Docker files remain available in the experimental/ directory for those who want to tinker, but with explicit caveats.

The One-Command Installation Script

What does Reconya’s automated installation actually do under the hood? The install.sh script detects your operating system, installs Go, Node.js, and nmap, configures critical nmap setuid permissions for raw socket access, and sets up the application as a system service.

git clone https://github.com/Dyneteq/reconya.git
cd reconya
./install.sh

The script performs OS detection (macOS, Windows, Debian/RHEL families), uses native package managers (Homebrew, apt, yum) to install dependencies, executes chmod u+s $(which nmap) to grant CAP_NET_RAW capabilities, downloads Go modules, compiles the binary, installs Node dependencies, and registers a systemd or LaunchAgent service for automatic startup.

Application Scenario: A systems administrator needed to deploy Reconya across ten Linux monitoring nodes. Rather than manually repeating steps, they wrapped the install script in an Ansible playbook with a custom .env template. The playbook executed in 30 minutes, ensuring consistent nmap permissions and eliminating the common failure point of forgotten setuid configuration.

Author Reflection: While automation is convenient, I’ve learned the hard way that running scripts without understanding their privilege changes is risky. The first time I used install.sh, I didn’t realize it modified nmap’s capabilities. Now I always review scripts that touch system permissions. Security and convenience balance on informed consent.

Manual Installation for Control Freaks

What steps does the manual installation process reveal about Reconya’s architecture? Manual setup involves installing Go 1.21+, Node.js 18+, and nmap separately, then configuring permissions, cloning the repository, setting up the backend environment, and launching the service — a process that exposes the tool’s modular design.

# Install dependencies (Ubuntu example)
sudo apt-get install nmap golang nodejs

# Critical permission configuration
sudo chown root:admin $(which nmap)
sudo chmod u+s $(which nmap)

# Application setup
cd reconya/backend
cp .env.example .env
# Edit .env to set credentials
go mod download
go run ./cmd

Windows Special Handling: The README specifically addresses SQLite CGO requirements on Windows, suggesting CGO_ENABLED=1 and providing a .bat script. This reflects pragmatic cross-platform support — not seamless universality, but documented workarounds.

Application Scenario: A network engineer on an isolated air-gapped network couldn’t use the install script due to lack of internet access. By following the manual steps with pre-downloaded dependencies, they successfully deployed Reconya, gaining visibility into a secure environment where automated tooling was prohibited.

From Zero to Operational: Your First 30 Minutes with Reconya

How do you transition from a successful installation to actively monitoring your network? The workflow involves securing default credentials, defining network segments, initiating scans, and interpreting the real-time device intelligence that populates the dashboard.

First Login and Security Hardening

What immediate security steps must you take after installation? Change the default admin/password credentials in backend/.env, generate a strong JWT secret key, and restart the service before exposing the web interface to any network access.

# In backend/.env
LOGIN_USERNAME=netadmin
LOGIN_PASSWORD=complex_random_string
JWT_SECRET_KEY=$(openssl rand -hex 32)

The service binds to http://localhost:3008 by default (not 3000, which is the Node dev server). Accessing it with default credentials is a critical security risk that must be remediated immediately in any production or shared environment.

Application Scenario: A security researcher deployed Reconya on a cloud VPS to monitor a honeypot network. Before exposing port 3008, they automated credential generation in their deployment script, ensuring each instance had unique, random passwords. This prevented a scan of their scanner, which would have exposed sensitive asset intelligence to attackers.

Author Reflection: I once forgot to change default credentials on a test deployment exposed to my home network. Within 24 hours, a port scan from a curious family member’s compromised IoT device hit the login page. Default passwords are not just a security anti-pattern; they’re an incident waiting to happen. Always treat credential setup as step zero, not step one.

Network Configuration Strategies

How should you define networks in Reconya for optimal results? Use CIDR notation (192.168.1.0/24) instead of IP ranges for clarity, start with a single /24 subnet for home use, and create multiple network profiles for enterprise environments with different scan frequencies (e.g., DMZ every 5 minutes, office LAN every 30 seconds).

Core Workflow:

Dashboard → Add Network → Enter CIDR → Select Network → Start Scan

Once scanning begins, the dashboard streams discovered devices via WebSocket. New devices appear highlighted, and status changes (online/offline) update in real time without page refreshes.

Application Scenario: A hospital IT administrator created separate Reconya networks for the guest Wi-Fi, medical device VLAN, and administrative LAN. By setting different scan intervals, they balanced the need for tight medical device monitoring (10-second intervals) against lower-priority guest network scans (2-minute intervals), reducing overall network load by 40%.

Deep-Diving into Device Intelligence

What actionable information can you extract from Reconya’s device details view? Clicking any device reveals MAC vendor identification, multi-protocol hostname resolution, OS fingerprint confidence scores, open ports with service banners, and automatic screenshots of web interfaces.

This granularity turns a simple IP list into an asset inventory. The MAC vendor quickly distinguishes Intel laptops from Espressif IoT modules. Hostname resolution aggregates DNS, mDNS, and NetBIOS results, sometimes revealing dual identities like living-room-tv.local (mDNS) and ANDROID-TV (NetBIOS) that indicate a smart TV. OS detection provides confidence percentages, and web screenshots visually confirm management interfaces without manual browser visits.

Application Scenario: During an internal breach investigation, an analyst used Reconya’s screenshot feature to identify a rogue device running an unpatched router firmware. The device’s open port 80 showed a login page with a known vulnerability. Manually verifying this would have taken 5 minutes per device; Reconya’s screenshots reduced triage time to 30 seconds per asset.

Under the Hood: The Scanning Engine and Performance Trade-offs

How does Reconya deliver comprehensive discovery without overwhelming the network? Its four-layer scanning pipeline uses adaptive strategies, controlled concurrency, and passive observation to minimize impact while maximizing coverage.

The Four-Layer Scanning Pipeline

What processes constitute a single scan cycle in Reconya? The pipeline consists of network discovery (30-second interval, adaptive ICMP/TCP), asynchronous device identification (parallel goroutines for MAC, hostname, OS), background port scanning (worker pool, top 100 ports), and web service screenshot capture (headless Chrome with strict timeouts).

Layer 1: Network Discovery
Privileged ICMP sweeps first; if blocked, fall back to TCP connects on ports 80, 443, 22, 21, 23, 25, 53, 135, 139, 445. Concurrently harvests ARP table entries for devices that don’t respond to probes but have communicated recently.

Layer 2: Device Identification
For each live IP, launches parallel goroutines to query MAC via ARP, resolve hostnames via DNS/mDNS/NetBIOS, and fingerprint OS using nmap’s probe signature database.

Layer 3: Port Scanning
A background worker pool performs connect() scans on the top 100 ports, then executes service/version detection on open ports. Workers are limited to prevent overwhelming target devices.

Layer 4: Web Enhancement
Detects HTTP/HTTPS services and launches headless Chrome to capture screenshots, page titles, and server headers. A 10-second timeout prevents stalled scans.

Performance Impact: A full /24 subnet scan completes in 15-30 seconds, generating only 2-5MB of traffic. This pulse-scanning approach is negligible compared to continuous packet capture or full 65,535-port scans.

Application Scenario: A managed service provider scanned 50 client networks nightly with Reconya. The tool’s low network footprint meant scans could run during business hours without impacting VoIP or video conferencing, unlike traditional vulnerability scanners that saturated links.

Author Reflection: The four-layer design embodies a “good enough” engineering philosophy. Why not scan all 65,535 ports? Because 90% of services live in the top 1000, and scanning the rest creates network noise that outweighs discovery value. Reconya’s default top-100 configuration is intentionally conservative. Security tools should never become the biggest traffic generator on the network.

The Elegant Simplicity of IPv6 Passive Monitoring

How does Reconya monitor IPv6 without active probes? On Linux, it uses netlink sockets to watch the kernel’s neighbor cache (ip neighbor show); on macOS/BSD, it uses sysctl interfaces. When the kernel processes neighbor advertisements, Reconya captures the IPv6-MAC mapping and address classification events in real time.

Implementation Details: The tool monitors NETLINK_ROUTE messages for new neighbor entries and interface address changes. It classifies addresses by prefix (Link-Local fe80::/10, Unique Local fc00::/7, Global 2000::/3) and color-codes them in the UI for rapid exposure assessment.

Application Scenario: In a red-team exercise, attackers used IPv6 SLAAC to bypass IPv4 firewall rules. The blue team, running Reconya’s passive monitor, detected the attacker’s Link-Local address via NDP within seconds, even though it had no IPv4 presence. This protocol-layer visibility is critical in modern dual-stack networks where IPv6 is often forgotten in defensive monitoring.

Configuration Tuning: Adapting Reconya to Your Network Topology

How do .env configuration options let you tailor Reconya to environments ranging from home labs to enterprise campuses? Key parameters control scan intervals, IPv6 monitoring scope, database paths, and credential security, allowing optimization for specific network characteristics.

# Security Hardening
LOGIN_USERNAME=netadmin          # Avoid 'admin' — too easy to guess
LOGIN_PASSWORD=16+ character random string
JWT_SECRET_KEY=$(openssl rand -hex 32)  # Critical for token security

# Performance
SCAN_INTERVAL=30                 # Increase to 60 in large networks to reduce load
PORT_SCAN_WORKERS=10             # Scale up to 30 on powerful hardware
SCREENSHOT_TIMEOUT=10s           # Reduce to 5s to speed up scans

# IPv6 Monitoring
IPV6_MONITORING_ENABLED=true
IPV6_MONITOR_INTERFACES=eth0,eth1  # Explicitly define in multi-NIC servers
IPV6_LINK_LOCAL_MONITORING=true    # Essential for internal networks
IPV6_MULTICAST_MONITORING=false    # Disable unless troubleshooting mDNS

# Database
SQLITE_PATH=/opt/reconya/data.db   # Use dedicated disk for I/O performance

Balancing Scan Frequency and Network Load

What formula governs the optimal scan interval? Recommended scan period = average device online duration / 10. For networks where devices stay online for hours, 60-second intervals capture 90% of activity while minimizing overhead.

Trade-off Analysis:

Faster intervals (10s): Better for BYOD environments with rapid device churn, but increases CPU and network utilization
Slower intervals (60s): Ideal for stable IoT networks, reducing overhead but potentially missing transient devices

Application Scenario: A stadium’s Wi-Fi network experienced extreme device churn during events. Tuning Reconya’s scan interval to 15 seconds captured 95% of spectator devices for capacity planning, while disabling IPv6 passive monitoring reduced CPU load by 20% on the underpowered network appliances.

Database Maintenance for Long-Term Stability

How do you prevent SQLite performance degradation over months of continuous operation? Rotate databases monthly using a cron job, enable WAL mode (which Reconya does by default), and monitor file size, archiving when it exceeds 500MB.

Practical Command:

# Monthly rotation via cron
0 2 1 * * cd /opt/reconya && sqlite3 data.db ".backup data-$(date +%Y%m).db" && rm data.db && systemctl restart reconya

Application Scenario: A manufacturing plant ran Reconya for six months, accumulating 2GB of event logs. Query performance degraded from milliseconds to seconds. Implementing monthly database rotation and pruning events older than 90 days restored sub-second query times and reduced storage costs by 70%.

Author Reflection: SQLite’s simplicity is a double-edged sword. It’s zero-configuration, but lacks built-in maintenance automation. The first time my database hit 1GB, I was frustrated by slow queries. Now I see it as a design choice: Reconya prioritizes simplicity over scalability, assuming users who need enterprise scale will implement their own maintenance routines. It’s a fair trade-off for a tool that runs flawlessly on a Raspberry Pi.

Operations: Troubleshooting and Keeping Reconya Healthy

What systematic approach resolves the most common Reconya issues? Use the built-in npm run status diagnostic, verify nmap permissions, check network reachability, resolve port conflicts, and implement monitoring for long-running instances.

Diagnostic Commands Every Admin Should Know

What does Reconya’s status command actually check? npm run status verifies Go version, Node.js version, nmap installation, nmap capabilities (CAP_NET_RAW), and confirms no zombie processes are bound to ports 3008 or 3000.

Status Output Decoded:

✓ nmap found with CAP_NET_RAW → Full scanning capability
✗ nmap requires setuid → Run chmod u+s $(which nmap)
✓ Go version 1.21+ → Meets requirements
✗ Node.js version < 18 → HTMX features may fail
⚠ Port 3008 in use → lsof -ti:3008 | xargs kill

Application Scenario: A novice user couldn’t get any scan results. Running npm run status immediately revealed nmap lacked setuid permissions. The fix took 10 seconds, but without the diagnostic command, they might have spent hours checking firewall rules and network configurations.

Solving the “No Devices Found” Mystery

What checklist isolates the root cause when Reconya returns zero devices? Verify network reachability with ip route, confirm nmap capabilities with getcap, check local firewall outbound rules (iptables/firewalld), validate CIDR syntax, and ensure you’re not scanning across VLANs without ARP proxy.

Advanced Debugging: Run tcpdump -i any icmp or tcp[13] & 2 == 2 during a scan. If no packets appear, Reconya lacks permissions. If packets are sent but no responses return, the issue is network-layer filtering.

Application Scenario: An MSP technician deployed Reconya on a segmented network but scanned the wrong VLAN’s CIDR. The scan completed instantly with zero results. Using tcpdump, they saw no outbound packets, revealing the CIDR misconfiguration rather than a tool malfunction.

Handling Port Conflicts

How do you resolve when Reconya’s ports are already occupied? Reconya uses two ports: 3008 (Go API) and 3000 (Node dev server). Modify backend/.env to change the API port, or stop conflicting services with lsof -ti:3008 | xargs kill -9.

Production Tip: Disable the Node dev server in production by editing the start script to launch only the Go binary, freeing port 3000 and reducing resource usage.

Application Scenario: A developer ran multiple Reconya instances to monitor different data center zones. By setting PORT=3008, PORT=3009, PORT=3010 in each .env file, they avoided conflicts and could run all instances on a single management host.

Long-Term Stability Considerations

What issues emerge when Reconya runs 24/7 for months? Monitor for slow memory growth (restart weekly), log file bloat (configure logrotate), and orphaned nmap processes (check with ps aux | grep nmap).

Monitoring Script Example:

# Check for stale nmap processes
if [ $(ps aux | grep -E "nmap.* reconya" | grep -v grep | wc -l) -gt 5 ]; then
  pkill -f "nmap.*reconya"
  systemctl restart reconya
fi

Application Scenario: A security firm’s persistent honeypot analysis node experienced occasional Reconya crashes. Implementing a systemd service with Restart=always and RestartSec=10, plus a weekly cron restart, achieved six months of uninterrupted uptime.

Author Reflection: The first time I found a zombie nmap process hoarding CPU, I blamed Reconya. Then I realized my scan interval was set to 1 second in a misconfigured test. Tools are only as stable as their configurations. The README’s warning about “services keep crashing” often points to user misconfiguration, not code defects. Always validate your .env before blaming the tool.

Architecture and Design Philosophy: Why Go, HTMX, and SQLite?

What technical choices enable Reconya’s unique blend of power and simplicity? Go provides static binaries with native concurrency for I/O-bound scanning, HTMX enables dynamic UI without JavaScript frameworks, and SQLite offers zero-configuration persistence, making the tool deployable anywhere from a Raspberry Pi to a server.

The Go+HTMX+SQLite Stack

Why these three technologies? Go compiles to a single binary with no runtime dependencies, handles thousands of concurrent goroutines efficiently for network scanning, and cross-compiles easily for different platforms. HTMX shifts dynamic behavior to the server, sending HTML fragments over the wire instead of JSON, eliminating the need for React/Vue and reducing frontend complexity by 80%. SQLite embeds directly, requiring no database server setup, perfect for a tool designed for single-node monitoring.

Comparison: A Python/Flask/PostgreSQL equivalent would require a virtual environment, database server installation, and complex deployment. Reconya’s stack reduces operational overhead by an order of magnitude while delivering comparable core functionality.

Application Scenario: A network consultant carried Reconya on a USB stick, deploying it on client systems in minutes without internet access or package managers. The static Go binary and embedded SQLite database enabled offline operation, a scenario impossible with dependency-heavy alternatives.

Author Reflection: I’ve seen too many projects adopt Kubernetes and microservices for problems that don’t need them. Reconya’s monolithic design is intentionally anti-trendy. It sacrifices scalability beyond a single node for unparalleled simplicity. For its target use case — network asset discovery — this is the correct trade-off. Not every tool needs to scale to a million nodes.

State Machine Design for Reliable Scans

How does Reconya prevent resource leaks and ensure clean shutdowns? The scanning engine uses a state machine (Idle → Discovering → Identifying → PortScanning → Screenshotting → Monitoring) synchronized with Go’s context.WithCancel() and sync.WaitGroup. When a user clicks “Stop,” all goroutines receive the cancellation signal and exit gracefully.

Implementation Detail: The scanner channels status updates via WebSocket, but if a client disconnects, the server-side scan continues for 30 seconds before timing out. This prevents partial scans from leaving zombie processes.

Application Scenario: An analyst started a large scan across a /16 network (65,534 addresses) then realized it would take too long. Clicking “Cancel” terminated all nmap subprocesses within seconds, freeing up CPU. Without proper context cancellation, these processes could have run for hours.

Practical Summary and Implementation Checklist

Quick-Start Checklist

[ ] Confirm administrator/root access on target system
[ ] Clone repository: git clone https://github.com/Dyneteq/reconya.git
[ ] Run installer: ./install.sh (review script first in production)
[ ] Verify nmap permissions: npm run status must show “with CAP_NET_RAW”
[ ] Edit backend/.env: Change default password and JWT secret
[ ] Start service: npm run start
[ ] Access dashboard: http://localhost:3008
[ ] Add network: Enter CIDR (e.g., 192.168.1.0/24)
[ ] Initiate scan: Click “Start Scan” and monitor real-time results
[ ] Secure access: Configure firewall to restrict port 3008 to management IPs

Production-Ready Configuration Template

# backend/.env for enterprise deployment
LOGIN_USERNAME=netadmin
LOGIN_PASSWORD=$(openssl rand -base64 32)
JWT_SECRET_KEY=$(openssl rand -hex 32)
DATABASE_NAME="reconya-prod"
SQLITE_PATH="/opt/reconya/data/reconya.db"
SCAN_INTERVAL=60
PORT_SCAN_WORKERS=30
IPV6_MONITORING_ENABLED=true
IPV6_MONITOR_INTERFACES=eth0
LOG_LEVEL=warn

One-Page Overview

What: Reconya is a Go+HTMX network reconnaissance tool for real-time asset discovery.
Why: Fills the gap between complex enterprise tools and bare command-line scanners.
Key Features: IPv4 nmap integration, IPv6 passive monitoring, device fingerprinting, web screenshots.
Install: Local installation only (Docker experimental). Use ./install.sh or manual setup.
Security: Immediately change default admin/password in backend/.env.
Use: Add CIDR network → Start scan → View real-time device details.
Performance: Scans /24 subnet in 15-30s, ~2-5MB traffic, <100MB memory.
Troubleshoot: Run npm run status, verify nmap setuid, check CIDR syntax.
Maintain: Rotate SQLite database monthly, monitor for orphaned nmap processes.
Limitations: No Docker MAC discovery, cross-VLAN needs ARP proxy, SQLite not for >10k devices.

Frequently Asked Questions

Q1: Will Reconya work in a Docker container?
A: Only partially. Docker’s network isolation blocks Layer 2 MAC discovery. For full functionality, including complete device identification, local installation is required. Docker files are in the experimental/ directory for testing only.

Q2: Why does Reconya need root or nmap with setuid?
A: MAC address discovery requires raw socket access to send ICMP probes and read ARP tables. Without CAP_NET_RAW, nmap falls back to TCP connects, which can’t retrieve Layer 2 information. Run sudo chmod u+s $(which nmap) to enable this.

Q3: Can I scan multiple networks simultaneously?
A: Yes. Reconya supports multiple network profiles. Create separate CIDR entries for each VLAN or subnet, then switch between them in the dashboard. However, only one network can be actively scanned at a time per Reconya instance.

Q4: How does IPv6 passive monitoring affect CPU usage?
A: Minimal impact. Passive monitoring uses Linux netlink or BSD sysctl interfaces to receive kernel events. CPU usage is typically <1% as the tool only parses existing NDP traffic, it doesn’t generate any.

Q5: What’s the maximum network size Reconya can handle?
A: Practical limit is around 2,000-3,000 devices per SQLite database. Beyond that, query performance degrades. For larger networks, deploy multiple Reconya instances per subnet or modify the code to use PostgreSQL.

Q6: How do I integrate Reconya with my existing SIEM?
A: Query the SQLite database directly (data/reconya-dev.db). Key tables: devices (assets), events (scan logs), networks (config). Or expose metrics by adding a Prometheus endpoint to the Go code. Simplest: cron job that exports new devices to CSV for SIEM ingestion.

Q7: Why are some MAC addresses missing in the scan results?
A: Three reasons: 1) nmap lacks setuid permissions, 2) scanning across routers (different broadcast domain), 3) target device doesn’t respond to ARP. Run npm run status to verify permissions, and ensure you’re scanning a local subnet, not a routed network.

Q8: Can Reconya identify what applications are running on a device?
A: Partially. It scans top 100 ports and grabs service banners (e.g., “OpenSSH 7.4”). For web services on 80/443/8080, it captures screenshots and page titles. Deep application-layer analysis requires additional tools like Nmap’s NSE scripts or specialized scanners.