Skip to main content

HTTP

🎯 Purpose​

Enable communication via an HTTP interface to centralize collected data between machines and the Watchman agent.

Simplify the setup

Save time by using our automatic installation script with a single command.

Download the script here

How to use:​

  1. Download the installation script.

  2. Edit the environment variables in the file to fit your network.

  3. Make the script executable depending on your system:

    • Linux

      chmod +x watchman-http-server.sh

    • Windows

      Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

  4. Run the script on each target machine in the network.

  5. And voilà, you’re ready! 🎉

1️⃣ HTTP Server Installation​

On each machine in the network to be scanned, install the package:

pip install watchman-http-server

2️⃣ Open the HTTP port (e.g., 8080)​

🔐 Linux​

sudo ufw allow 8080/tcp

🔐 Windows: Opening the HTTP port (TCP 8080)​

To allow machines to listen or communicate via port 8080, you need to create a rule in the Windows firewall:

Steps to allow port 8080:​

  1. Open Windows Defender Firewall with Advanced Security

    • Click Start
    • Type Windows Defender Firewall with Advanced Security and open it

  2. Create a new inbound rule

    • In the left pane, click Inbound Rules
    • In the right pane, click New Rule…

  3. Choose rule type

    • Select Port
    • Click Next

  4. Configure the port

    • Choose TCP

    • Select Specific local ports and enter:

      8080

    • Click Next

  5. Allow the connection

    • Select Allow the connection
    • Click Next

  6. Choose the profile

    • Check boxes according to the network type concerned:

      • Domain: for a corporate network with Active Directory domain
      • Private: for home or trusted networks
      • Public: for public networks (optional based on needs)

    • Click Next

  7. Name the rule

    • Give the rule a name, for example:

      Watchman Agent HTTP - Port 8080

    • Click Finish

Port 8080 is just an example. You can use any available port.

3️⃣ Securing the communication​

  • Generate an API key (using any secure generator)
  • Use the same API key on all machines for simplicity, or a different key per machine for stronger security
  • Define the authorized IP address allowed to interact with the HTTP server (usually the agent’s IP)

⚠️ The more unique the key per machine, the higher the security.

4️⃣ Starting the HTTP server​

watchman-http-server runserver \
  --port <PORT> \
  --api-key <API_KEY> \
  --addresses <AGENT_IP_ADDRESS> \
  -d detach
  • --port: the listening port (e.g., 8080)
  • --api-key: your authentication key
  • --addresses: the Watchman agent IP address authorized to connect
  • -d detach: to run the server in the background

✅ Correct HTTP configuration ensures secure and automated transfer of data collected by the agent.