Polaris — pr0t31n

How It Works

Polaris is a Flask/SocketIO C2 (Command and Control) server manager and real-time connection dashboard. It manages and monitors three core services — Chisel reverse tunnel server, iodined DNS tunnel server, and Metasploit Framework console — providing a unified web dashboard on port 5900 for tracking connected pentest appliances and active tunnels.

Architecture: Polaris consists of three layers:

Supervisor (supervisor.py) — Process lifecycle manager that starts, stops, restarts, and re-attaches to the three managed services. Processes are launched detached (new session) and tracked via PID files in /var/run/. The supervisor survives Polaris restarts by re-attaching to running processes on startup.
Monitors (monitor.py) — Four background polling threads that collect live state:
- ChiselMonitor — Tails /var/log/chisel.log, parses session open/close and proxy-listener events via regex. Replays the log on startup to reconstruct current session state. Detects chisel server restarts (clears stale sessions). Clears all sessions if the chisel server process is not running.
- ServiceHealthCheck — Polls pgrep every 10 seconds to check if chisel server, iodined, and msfconsole processes are alive. Emits SocketIO events on state changes.
- IodineMonitor — Probes the DNS tunnel subnet (default 10.53.53.0/24) with ICMP pings every 15 seconds to detect connected iodine clients. Checks /sys/class/net/dns0 for tunnel interface existence.
- MetasploitMonitor — Captures the tmux pane output (last 200 lines) from the polaris-msf session, parsing "Meterpreter session N opened" / "session N closed" events. Also reads /var/run/polaris_sessions.json as a fallback data source.
Device Registry — Maps hostnames to device IDs via device_registry.json. Device IDs are used to compute per-appliance port offsets for Vantage (25100+id), Crucible (25500+id), Nessus (28834+id), and SOCKS (1081+id) tunnels.

Dashboard API: The /api/status endpoint aggregates all monitor data into a unified view showing per-appliance connection state (chisel connected, DNS tunnel active, Meterpreter session), computed tunnel ports, service health, supervisor status, and a rolling event timeline (last 200 events).

Service Control: REST endpoints (/api/service/<name>/start|stop|restart, /api/start-all, /api/stop-all) allow starting, stopping, and restarting services through the web UI. The supervisor handles port conflicts, stale process cleanup, orphan detection, and automatic TLS certificate generation for Chisel.

Security

Polaris runs without authentication by design. It is deployed exclusively on the C2 server and is not intended to be exposed to the internet or to pentest targets. The SECRET_KEY is randomly generated at startup (not persisted). SocketIO CORS is set to allow all origins since the dashboard is accessed from the operator's workstation.

TLS for Chisel: The supervisor automatically generates a self-signed TLS certificate (ECDSA prime256v1, 10-year validity) for the Chisel server if none is configured, stored in the keys/ directory. Custom certificates can be specified in config.yaml.

Firewall Management: The supervisor automatically opens required UFW ports (Chisel listen port TCP, DNS port 53/udp, C2 callback ports) when starting services.

Features

Configuration

YAML Configuration

Reads config.yaml for: c2.host (C2 server address), chisel settings (server_port, auth, tls, tls_key, tls_cert, enabled), dns_tunnel settings (domain, password, tunnel_net, enabled), and c2.ports (callback port list for UFW).

Dashboard

Unified Appliance View

Aggregates data from all monitors into a per-appliance status view showing chisel tunnel, DNS tunnel, and Meterpreter connection state, with computed port mappings for Vantage, Crucible, Nessus, and SOCKS proxies.

Real-Time SocketIO Events

Pushes chisel_update, chisel_closed, service_status, iodine_update, and msf_sessions events to connected dashboard clients for live status updates without polling.

Event Timeline

Maintains a rolling buffer of the last 200 connection/disconnection events with timestamps, served via the /api/status endpoint's events array.

Device Registry

Maps hostnames to integer device IDs via device_registry.json (auto-reloaded every 60 seconds). Device IDs drive per-appliance port offset calculations (base + device_id) for consistent tunnel port assignment.

Firewall

Automatic UFW Rules

Automatically opens required firewall ports via ufw when starting services: Chisel listen port (TCP), DNS 53 (UDP), and all configured C2 callback ports (TCP). Checks existing rules before adding.

Monitoring

Chisel Session Tracking

Tails /var/log/chisel.log in real-time (2-second polling), detecting new tunnel sessions (proxy listeners) and disconnections via regex. Replays the full log on startup to reconstruct current session state. Maps server-side ports to device IDs and service names via the base-port offset scheme.

Service Health Checks

Polls process tables every 10 seconds via pgrep to detect whether chisel server, iodined, and msfconsole (including ruby.*msf pattern) are running. Emits SocketIO events only on state changes to minimize traffic.

Iodine Client Detection

Probes the DNS tunnel subnet (10.53.53.2 through 10.53.53.10) with ICMP pings every 15 seconds to detect connected iodine clients. Monitors /sys/class/net/dns0 for tunnel interface existence; clears clients when dns0 disappears.

Meterpreter Session Tracking

Captures last 200 lines from the polaris-msf tmux pane to detect Meterpreter session open/close events. Extracts remote IP and maps to hostname. Falls back to /var/run/polaris_sessions.json for external session data injection.

Security

Auto TLS Certificate Generation

Generates a self-signed ECDSA (prime256v1) certificate with 10-year validity for the Chisel server when no custom certificate is configured, using the C2 host as the CN.

Service Management

Chisel Server Control

Starts, stops, and restarts the Chisel reverse tunnel server. Handles port conflicts (kills stale chisel processes, stops meshcentral if occupying the port), orphaned process cleanup via pgrep, and automatic TLS certificate generation (ECDSA prime256v1). Supports --auth credential passthrough and configurable listen port.

iodined DNS Tunnel Control

Manages the iodined DNS tunnel server. Verifies NS delegation via dig before starting, configures the tunnel network subnet (default 10.53.53.1/24), handles daemonization detection, and opens UFW port 53/udp automatically.

Metasploit Console Management

Launches msfconsole inside a dedicated tmux session (polaris-msf) with a resource script (listener.rc). Runs prep_handler.py before launch, opens C2 callback ports via UFW, and manages the tmux session lifecycle.

Start/Stop All Services

Batch start or stop all enabled services with a single API call (/api/start-all, /api/stop-all). Respects per-service enable/disable configuration from config.yaml.

Process Reattachment

On startup, the supervisor re-attaches to already-running services via PID files in /var/run/, allowing Polaris to restart without disrupting active tunnels or sessions.

Use Cases

Multi-Appliance Pentest C2 Hub

Deploy Polaris on the C2 server to manage reverse tunnels from multiple pentest appliances. Each appliance connects via Chisel, and Polaris tracks which appliances are online, their tunnel ports, and active Meterpreter sessions from a single dashboard.

Chisel Reverse Tunnel Orchestration

Use Polaris to start and monitor the Chisel server with TLS and authentication. The dashboard shows which appliances have active tunnel sessions and their assigned port mappings for Vantage, Crucible, and Nessus access through the tunnel.

DNS Tunnel Fallback Management

When Chisel (TCP) tunnels are blocked, use Polaris to manage iodined DNS tunnels as a fallback channel. The iodine monitor detects which clients are reachable through the DNS tunnel subnet via ICMP probes.

Metasploit Session Dashboard

Track Meterpreter sessions from a single dashboard alongside tunnel connections. Polaris parses msfconsole output from the tmux session to show active session IDs, remote IPs, and associated hostnames.

Service Recovery After Reboot

After a C2 server reboot, Polaris re-attaches to any services that survived (via PID files) and can restart those that did not, maintaining tunnel continuity with minimal manual intervention.

CLI Reference

Third-Party Tool Invocations

Commands and flags used when this tool invokes third-party dependencies during operation.

chisel

Reverse tunnel server with SOCKS5 proxy support. Polaris starts it with --reverse --socks5 --v and optional TLS and auth flags.

chisel server --reverse --socks5 --v --port 443 --tls-key keys/chisel_tls.key --tls-cert keys/chisel_tls.crt --auth <credentials>

iodined

DNS tunnel server daemon. Polaris starts it with -c (compression), -P (password), tunnel subnet, and domain arguments.

iodined -c -P <password> 10.53.53.1/24 tunnel.example.com

msfconsole

Metasploit Framework console. Polaris launches it inside a tmux session with a resource script (listener.rc) for pre-configured handlers.

msfconsole -r /opt/pr0t31n/Polaris/listener.rc

tmux

Terminal multiplexer used to run msfconsole in a detached session (polaris-msf) that Polaris can capture output from and manage.

tmux new-session -d -s polaris-msf 'msfconsole -r listener.rc'

tmux capture-pane -t polaris-msf -p -S -200

tmux list-panes -t polaris-msf -F '#{pane_pid}'

tmux kill-session -t polaris-msf

pgrep

Process lookup used by both the service health monitor (checking if services are alive) and the supervisor (finding orphaned/stale processes).

pgrep -f 'chisel server'

pgrep -f iodined

pgrep -f msfconsole

pgrep -f 'ruby.*msf'

ping

ICMP probe used by the IodineMonitor to detect reachable clients on the DNS tunnel subnet (10.53.53.2 through 10.53.53.10).

ping -c 1 -W 1 10.53.53.2

openssl

Generates self-signed TLS certificates (ECDSA prime256v1, 10-year validity) for the Chisel server when none are configured.

openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -nodes -keyout chisel_tls.key -out chisel_tls.crt -days 3650 -subj /CN=<c2_host>

dig

DNS lookup used by the supervisor to verify NS delegation for the iodine DNS tunnel domain before starting iodined.

dig +short NS tunnel.example.com

ufw

Firewall management to automatically open required ports (Chisel TCP, DNS 53/udp, C2 callback ports) when starting services.

ufw allow 443/tcp

ufw allow 53/udp

ufw status

ss

Socket statistics used to detect port conflicts before starting the Chisel server.

ss -tlnp sport = :443

ps

Process status used to identify the name of a process occupying a conflicting port.

ps -p <pid> -o comm=

systemctl

Used to stop meshcentral if it is occupying the Chisel listen port.

systemctl stop meshcentral

Invocation Methods

Method	Usage
CLI — Direct	`cd /opt/pr0t31n/Polaris && python3 app.py` Run directly with command-line arguments.
CLI — Settings File	`cd /opt/pr0t31n/Polaris && python3 app.py --config config.yaml` Configure via config.yaml (YAML), then run.
Web UI	`https://localhost:5900` Flask web interface — start the app then open in browser.

Integration

Depends On

LandNav (drop device)

Used By

Nexus (health check)

Third-Party Dependencies & Credits

Tool / Library	Developer	Type	Link
Flask	Pallets / Armin Ronacher	python	https://github.com/pallets/flask
Flask-SocketIO	Miguel Grinberg	python	https://github.com/miguelgrinberg/Flask-SocketIO
chisel	Jaime Pillora (jpillora)	system	https://github.com/jpillora/chisel
iodine / iodined	Erik Ekman (yarrick)	system	https://github.com/yarrick/iodine
Metasploit Framework	Rapid7	system	https://github.com/rapid7/metasploit-framework

Metadata

Name	Polaris
Category	Egress & Control
Version	1.2.4
Install Path	`/opt/pr0t31n/Polaris`
Main File	`app.py`
Port	5900
GitHub	https://github.com/pr0t31n/Polaris.git
Requires	LandNav