Agents

An agent in sslbrain is a set of scripts that knows how to install a certificate on a specific platform. When sslbrain deploys a certificate to a server, it is an agent that does the actual work: imports the certificate, configures the web server and restarts services as needed.

Built-in Agents

sslbrain ships with agents for the most common platforms. All built-in agents are maintained and updated by FairSSL and tested against each new version before release.

Windows Service Agent

The Windows Service Agent is a lightweight MSI package installed on Windows servers. It pulls signed tasks from sslbrain via outbound HTTPS, so no open ports or WinRM configuration is required.

Deploy via GPO, SCCM or Intune. Ideal for environments with strict firewall rules.

Community Agents

Community agents are written by users and shared with all sslbrain installations. Each community agent is:

1. Submitted by a user
2. Reviewed by FairSSL for security and quality
3. Signed with FairSSL's ECDSA P-384 key
4. Made available to all sslbrain installations

Community agents cover platforms not covered by the built-in agents, e.g. Postfix, HAProxy, Tomcat, Synology or specific cloud services.

You can find community agents in sslbrain under Agents > Community. Install them with a single click.

Share a community agent

Have you built an agent that could be useful to others? Share it:

1. Open your custom agent in sslbrain
2. Click Share with community
3. The agent is sent to FairSSL for review

Once the agent is approved and signed, it becomes available to all sslbrain installations via Agents > Community.

Custom Agents

If you have a platform not covered by either built-in or community agents, you can build your own.

sslbrain has a GUI editor for custom agents. For simple setups (e.g. copy certificate to a specific path and restart a service) no programming is needed. The editor guides you through the steps.

For more advanced needs, you can write agent scripts directly in YAML format.

YAML Format

An agent is defined in an agent.yml file. Here is a simple example that copies a certificate and key to a server and restarts a service:

name: my-custom-agent
description: Installs certificate for my application
platform: linux

steps:
  - name: Copy certificate
    action: write_file
    path: /etc/myapp/tls/cert.pem
    content: "{{ certificate_pem }}"
    mode: "0644"

  - name: Copy private key
    action: write_file
    path: /etc/myapp/tls/key.pem
    content: "{{ private_key_pem }}"
    mode: "0600"

  - name: Restart application
    action: run_command
    command: systemctl restart myapp

verify:
  - name: Check TLS connection
    action: tls_check
    host: localhost
    port: 443

Variables such as {{ certificate_pem }} and {{ private_key_pem }} are replaced automatically by sslbrain during deployment.

Available variables

Available actions

You can create and test custom agents directly in sslbrain's GUI editor under Agents > Custom > New agent.

Code Signing

Security is central to agents, because they are executed with elevated privileges on your servers.

All agents (built-in, community and custom) are signed:

Custom agents you create yourself are signed with your installation's local key. They can only be executed on servers connected to your sslbrain instance.