Appliance deployment (remote)¶

Some devices cannot run an Agent: firewalls, load balancers and application delivery controllers. Since Agent 1.5.0, an Agent that already runs on a Windows or Linux machine can deploy a renewed certificate to such a device over the device's own HTTPS management API. The certificate is issued and renewed on the Agent machine as usual; a remote.deploy step then uploads the certificate and key to the appliance, optionally binds it to a service, and reads it back from the device to check that the new certificate is there.

The Agent connects outbound to the appliance's management port over HTTPS (443 unless you set another port). Nothing connects to the Agent, and the appliance needs no inbound access to CertIntel. Allow HTTPS from the Agent machine to the management interface in every firewall between them.

Templates¶

The appliance templates (Agent 1.5.0+) appear in the Windows desktop app under Appliances (remote), in the terminal interface under T on the Workflows screen (New workflow from a template), and in dashboard assignments. Each one has two steps: Obtain certificate, then Deploy to the template name (remote.deploy, 600-second timeout, one retry after 30 seconds; a failure stops the run).

Fields every appliance template has¶

F5 BIG-IP¶

The Agent creates /<partition>/<name>.crt, <name>.key and, when there is a chain, <name>-chain.crt, then removes the uploaded files from the device (best effort). With a client SSL profile, the profile's certificate key chain is replaced by the new certificate, key and chain; the Agent then checks that the profile uses them.

Tested against a simulated API, not a real device. The request shapes come from the iControl REST documentation. Not confirmed on a device: that updating a profile replaces its whole certificate key chain list.

FortiGate¶

The certificate name, with the fingerprint suffix, may be at most 35 characters in all. Administrator interface sets the admin server certificate; SSL VPN sets the SSL VPN server certificate of the VDOM.

Tested against a simulated API, not a real device. The request shapes come from the FortiGate documentation and the Fortinet Developer Network (sign-in required). Not confirmed on a device: the Agent sends the leaf certificate followed by the chain in one upload; whether FortiOS accepts the intermediates that way depends on its version.

Palo Alto Networks PAN-OS¶

The Agent imports the key pair, then each intermediate as <name>-ca<N>, and optionally sets the certificate in the shared SSL/TLS service profile.

Tested against a simulated API, not a real device. The request shapes come from the PAN-OS documentation. Not confirmed on a device: that a certificate entry's public-key element holds the certificate PEM (taken from the documented configuration schema).

NetScaler ADC¶

The certificate and key files are uploaded as /nsconfig/ssl/<pair>-<fingerprint>.crt and .key. An existing certificate-key pair is updated in place and keeps its bindings; the pair name itself gets no suffix. The Agent then checks that the pair uses the new file.

Tested against a simulated API, not a real device. The request shapes come from the NITRO API reference. Not confirmed on a device: the certificate file carries the leaf followed by the chain with "bundle": "YES" (ADC 13.0 and later); linking a separately installed intermediate is left to the administrator.

SonicWall¶

The Agent imports a one-time PKCS#12 archive, optionally uses the certificate for HTTPS management, commits the pending changes and logs out. The passphrase of the one-time archive is part of the import URL, as the API describes it.

Tested against a simulated API, not a real device. Not every detail could be confirmed from the published SonicWall documentation: the import, read-back and HTTPS-management paths and request bodies are assumptions and must be confirmed against a device before production use.

Object names on the device¶

Each issued certificate gets its own object on the device, named <base>-<the first 8 hexadecimal digits of its SHA-256>, so a renewal never overwrites an object a service is still using, and a retried run finds the object it uploaded before. <base> is the Certificate name on the device (characters the device does not allow become -, and the name is shortened to the device's limit); when it is empty, the first certificate name without *., or certintel.

Every renewal therefore adds objects. The Agent does not remove old certificates from the device yet: delete those no service uses any more on the device itself. If the device already holds a different certificate under the same name, the step fails (for example FortiGate already holds a different certificate named … ; remove it or choose another certificate name).

Checking the management certificate¶

The Agent checks the appliance's management certificate before it sends the credential:

The pinned fingerprint is the SHA-256 of the management certificate itself (the leaf, in DER form): 64 hexadecimal digits without colons. Compute it from the Agent machine, so you pin what the Agent sees, and compare it with the fingerprint the device shows in its own management console.

On Linux or any machine with OpenSSL:

openssl s_client -connect fw01.example.net:443 -servername fw01.example.net </dev/null 2>/dev/null \
  | openssl x509 -outform DER | sha256sum

On Windows PowerShell:

$hostName = 'fw01.example.net'; $port = 443
$tcp = [System.Net.Sockets.TcpClient]::new($hostName, $port)
$ssl = [System.Net.Security.SslStream]::new($tcp.GetStream(), $false, { $true })
$ssl.AuthenticateAsClient($hostName)
$cert = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new($ssl.RemoteCertificate)
$cert.GetCertHashString('SHA256').ToLowerInvariant()
$ssl.Dispose(); $tcp.Dispose()

The PowerShell example accepts any certificate only to read it; verify the result against the device console before you pin it. If a tool prints the fingerprint with colons or in upper case (AB:CD:…), remove the colons; the field expects 64 hexadecimal digits without colons (the pinned SHA-256 fingerprint must be 64 hexadecimal digits without colons).

A mismatch fails the step before the credential is sent: the management certificate (SHA-256 …) does not match the pinned fingerprint.

Credentials¶

A template's credential field never holds the credential itself, only where it comes from.

Local credential¶

Local means a local administrator stores the credential on the Agent machine, in the Agent's protected secret store:

certintel secret set remote WORKFLOW-ID:credential

Run it from an elevated prompt (Windows) or with sudo (Linux); it prompts without echo, and --stdin is available for automation. A username and password are entered as username:password; an API token as the token alone. The desktop app offers a Set… button next to the field (Local: set on this computer), and the terminal interface asks with a hidden prompt after saving (Set the local credential now). Until the credential is set, a run fails with credential not set: certintel secret set remote WORKFLOW-ID:credential. A local credential works while the configuration lock is on. Workflows created on the Agent machine always use local credentials.

Platform credential¶

A workflow created from a dashboard assignment may instead name a platform credential stored in CertIntel. The Agent fetches it at each run, sealed to a key only this Agent holds, and uses it in memory for that one step. This needs all of the following:

• A local opt-in. A local administrator allows it on the device: in the terminal interface, Settings → Platform credentials (appliances) → Receive appliance credentials from the CertIntel platform; in the desktop app, Settings → Platform credentials (appliances) → Allow platform credentials…; or "remote_credentials": "accept" in the configuration. The approval dialog reads Allow this agent to receive appliance credentials from the CertIntel platform. CertIntel can never turn this on, and neither can an assignment.
• The configuration lock is off. While the lock is on, platform credentials are not fetched (Configuration lock is on; platform credentials are not fetched.).
• The workflow was created by a dashboard assignment that names the credential. A workflow created on the device that names a platform credential is refused.
• An approved sealing key. Turning the opt-in on creates the Agent's sealing key. CertIntel pins the first key the Agent reports. A different key (after a re-enrolment or a rotation) must be approved on the Agent's host page in the dashboard before CertIntel delivers anything to it; see Platform credentials.

Each delivery is valid for 5 minutes and bound to the organization, the assignment, the credential, the delivery and the sealing key. To replace the sealing key (for example after a suspected compromise of the machine), run certintel secret rotate-sealing-key as an administrator, or use Rotate sealing key… in the desktop app or the Sealing key row in the terminal interface; then approve the new key on the host page.

What is logged¶

• The Agent's activity log records remote-credential-fetched (with the credential, delivery, assignment, workflow, step, run and key ids, or the local secret name), remote-credential-refused (with the reason), sealing-key-created and sealing-key-rotated. Only ids and reasons are recorded, never the credential.
• A successful run's summary names the driver, the host, the object on the device and the binding, and ends with verified. With an unverified management certificate it adds management certificate NOT verified (insecure).
• When a step fails, the redacted end of its output goes to CertIntel with the failure report (see failed step output); the credential and its base64 forms are removed from it.
• In CertIntel, every delivery and refused delivery of a platform credential is in the activity log.

The credential never appears in command-line arguments, environment variables, logs, the activity log, the Agent's state files or reports.

Custom programs: the script driver¶

For a device without a built-in template, a workflow created on the Agent machine can use remote.deploy with driver: "script" to run a program of your own. CertIntel never proposes it, and it is refused in dashboard assignments (the script driver runs only in workflows created on this computer).

• options.executable is the absolute path of a regular executable file; options.arguments is an optional list. Arguments cannot reference secrets (the script gets its credential on stdin; arguments cannot reference secrets).
• The program reads one JSON document on standard input: schema (1), driver, template (id, version), run_id, target (host, port, tls with verify and, when set, pin_sha256 or ca_file), credential (kind and username/password or token), certificate (names, fingerprint_sha256, thumbprint_sha1, not_after, certificate_pem, chain_pem, private_key_pem) and variables. The program must check the management certificate itself as target.tls says.
• The environment is minimal, not the service's: on Linux PATH=/usr/sbin:/usr/bin:/sbin:/bin and LANG=C.UTF-8; on Windows SystemRoot, windir, SystemDrive, ComSpec, PATHEXT, PATH, TEMP and TMP; plus CERTINTEL_WORKFLOW_ID, CERTINTEL_STEP_ID, CERTINTEL_DRIVER and CERTINTEL_RUN_ID.
• Exit code 0 is success (the script exited with code N otherwise). The step outputs exitCode and the end of stdout and stderr, with the credential removed.
• On timeout the program is stopped with its child processes (the program did not finish within the step timeout and was stopped with its child processes): a process group on Linux, a job object on Windows. On Windows, a child process the program starts in the instant before it is placed in the job can escape that stop.

Related pages¶

• Platform credentials - storing appliance credentials in CertIntel and approving sealing keys
• Dashboard-assigned workflows - proposing an appliance template to an Agent
• Modular workflow builder & action inputs - template fields and actions
• Microsoft services - Windows server roles on the Agent machine itself
• Linux service targets - HAProxy, Caddy, Postfix and other local services
• Windows Agent and Linux Agent - the configuration lock