Windows Service Agent

Windows Service Agent is the recommended way to connect Windows servers to sslbrain. The agent runs as a Windows Service, calls out to sslbrain on its own and requires no open inbound ports.

Download & Install

Download

Download the MSI installer from the Downloads page in sslbrain. The file is pre-configured with your sslbrain server's address and a registration token, so the agent knows where to connect.

Interactive installation

Run the MSI file on the Windows server. The installation is standard Windows style: next, next, finish. There is no configuration during installation, everything is embedded in the MSI file.

The agent is installed as a Windows Service (SSLBrainAgent) that starts automatically with the server.

Silent installation

For deployment to many servers, you can install without a GUI:

Terminal 
msiexec /i SSLBrainAgent.msi /qn SERVER=https://sslbrain.local REGISTRATION_TOKEN=abc123

Parameters:

Parameter Description
SERVERsslbrain server URL
REGISTRATION_TOKENOne-time token from sslbrain (generated under Downloads)
/qnSilent installation without UI

Tip: The token is only used during registration. Afterwards, the agent uses its own API token.

How It Works

The agent uses a simple pull model:

1

Check-in

The agent contacts sslbrain every 5 minutes via HTTPS.

2

Fetch tasks

sslbrain responds with a signed task package (e.g. "install this certificate on IIS").

3

Verify signature

The agent verifies the ECDSA P-384 signature before execution. Invalid signatures are rejected.

4

Execute

The agent runs the task locally on the server.

5

Report

The result is sent back to sslbrain at the next check-in.

All communication is outbound from the agent. sslbrain never opens a connection to the server.

Server discovery

The agent finds sslbrain automatically on startup. It tries in this order:

  1. Registry: if ServerURL is set in the registry, it is used directly
  2. DNS SRV record: the agent looks up _sslbrain._tcp.your-domain. If the DNS server returns an SRV record, the agent uses that address
  3. sslbrain Cloud: the agent contacts sslbrain Cloud with its registration token and receives the server's address in return

For most installations, you don't need to think about this. The MSI file contains the server address, and it is written to the registry during installation.

Tip: DNS SRV is useful if you have many servers and want to avoid hardcoding the address. Create this record in your DNS zone:

DNS 
_sslbrain._tcp.example.com. 3600 IN SRV 0 0 8443 sslbrain.example.com.

Registry Settings

All agent settings are stored in the registry under:

Registry 
HKLM\SOFTWARE\SSLBrain\
Key Type Default Description
ServerURL REG_SZ (from MSI) sslbrain server URL
AgentId REG_SZ (auto-generated) The agent's unique ID. Do not modify.
ApiToken REG_SZ (auto-generated) The agent's API token. Do not modify.
CheckInInterval REG_DWORD 300 Seconds between check-ins. Minimum 60.
ScriptPolicy REG_SZ SignedOnly SignedOnly = only signed scripts. TrustAll = allow unsigned (for testing only).
TrustSignedBefore REG_SZ (empty) ISO 8601 date. Reject scripts signed before this date (for key rotation).
LogLevel REG_SZ Info Debug, Info, Warning or Error

Note: Most installations need no changes. AgentId and ApiToken are generated automatically during registration and should never be changed manually.

GPO Deployment

For larger environments, you can distribute the agent via Group Policy:

1. Prepare MSI and registry

Place the MSI file on a network share that all servers can read:

UNC path 
\\filserver\software\SSLBrainAgent.msi

2. Create GPO

  1. Open Group Policy Management Console
  2. Create a new GPO and link it to the OU containing your servers
  3. Go to Computer Configuration > Policies > Software Settings > Software installation
  4. Right-click, select New > Package, and point to the MSI file on the network share

3. Configure registry via GPO

To set SERVER and REGISTRATION_TOKEN without interactive installation:

  1. In the same GPO, go to Computer Configuration > Preferences > Windows Settings > Registry
  2. Create the following values under HKLM\SOFTWARE\SSLBrain\:
    • ServerURL = your sslbrain server URL
    • RegistrationToken = a token from sslbrain

The servers register themselves automatically at the next Group Policy update and restart.

Tip: Alternatively, you can use the msiexec command from silent installation in a startup script.

Troubleshooting

Log files

The agent writes log files to:

Path 
C:\ProgramData\SSLBrain\logs\

The log file is rotated daily and kept for 30 days. Set LogLevel to Debug in the registry for more detailed logs.

Windows Event Log

The agent also writes to the Windows Event Log:

Field Value
LogApplication
SourceSSLBrainAgent

Important events (start, stop, registration, errors) are always written to the Event Log, regardless of the LogLevel setting.

Common issues

Problem: The agent does not start

Solution:

  • Check that the service SSLBrainAgent is set to Automatic startup
  • Check the Event Log for error messages at startup
  • Confirm that the account the service runs under has permissions to C:\ProgramData\SSLBrain\

Problem: The agent cannot connect to sslbrain

Solution:

  • Check that the server can reach sslbrain's address on the configured port (default 8443)
  • Check ServerURL in the registry, is the address correct?
  • Check the firewall for outbound HTTPS traffic
  • Try curl https://your-sslbrain:8443/api/health from the server to test the connection

Problem: The agent shows as "Offline" in sslbrain

Solution:

  • Check that the service is running: sc query SSLBrainAgent
  • Check the log file for errors
  • Restart the service: sc stop SSLBrainAgent && sc start SSLBrainAgent