@falconhunter-sec/agent

Live push-style Kali agent for the FalconHunter dashboard. Replaces the legacy bash poller with a Node.js client that:

• dispatches commands <500 ms after the dashboard queues them
• streams stdout line-by-line to the dashboard's terminal pane while the command is still running (no more waiting for nmap to finish to see output)
• handles long-running scans (20–30 min nuclei / sqlmap / nmap) without hitting any server request timeout
• runs many commands in parallel
• needs only outbound HTTPS — no inbound ports, NAT-safe

Quick start

On your Kali box:

npx -y @falconhunter-sec/agent@latest --token sk_kali_XXXX --server https://your-app.example

Copy the exact command from the dashboard's Connect your Kali screen — it already includes both --token and --server filled in for your account.

Ctrl+C to stop. Re-running picks up where it left off.

Options

| Flag | Default | Description | | ---------------- | ------- | ---------------------------------------------------------- | | --token, -t | — | Install token from the dashboard (sk_kali_…) | | --server, -s | — | FalconHunter server origin | | --poll | 500 | Dispatch poll interval in ms (min 150) | | --debug, -d | off | Verbose logs |

Env equivalents: FALCONHUNTER_TOKEN, FALCONHUNTER_SERVER.

How it works

┌─────────────┐  POST /api/public/agent/checkin (every 500ms)     ┌──────────┐
│  Kali (npx) │ ◄──── new pending commands (JSON batch) ───────── │  Server  │
│   Node 18+  │                                                   │ (worker) │
│             │  POST /api/public/agent/chunk (every ~750ms)      │          │
│             │ ────► incremental stdout/stderr (rolling buffer)─►│ DB row   │
│             │                                                   │ UPDATEs  │
│             │  POST /api/public/agent/chunk {done:true}         │          │
│             │ ────► final stdout + exit_code ─────────────────► │ realtime │
└─────────────┘                                                   └──────────┘
                                                                       │
                                                                       ▼
                                                    Dashboard terminal pane
                                                    subscribes via realtime
                                                    and renders live output.

The server's terminal pane is already subscribed to postgres_changes on the agent_commands row, so every chunk push appears as a live UI update.

Publishing (maintainer)

cd agent-cli
npm login
npm publish --access public

Until the package is published, you can run the agent straight from this repo:

node agent-cli/bin/falconhunter-agent.mjs --token sk_kali_... --server https://...

Troubleshooting

• HTTP 401 bad token — copy a fresh token from the dashboard, or click Rotate in Settings → Connect.
• No output in the dashboard but the local terminal shows the command running — check that chunk POSTs aren't blocked by an outbound firewall.
• Command fails with bash: <tool>: command not found — the dashboard auto-installs missing tools on the next attempt; just let it retry.