Egna skript

För en plattform som katalogen inte täcker skriver ni skriptet själva och laddar upp det som en anpassad agent under Agenter › Katalog. Appliancen signerar det med sin egen nyckel, och det körs bara på målservern, aldrig på appliancen.

Ladda upp en anpassad agent

Bara en Owner kan slå på anpassade agenter och ladda upp dem.
Licensen avgör hur många anpassade agenter appliancen kan ha: Free 1, Basic 3, Professional och Enterprise obegränsat. En ny version av en anpassad agent som ni redan har tar inte en plats till.
En anpassad agent kan inte anropa ett API från appliancen. Alla åtgärder körs på målservern.

Packa agenten som en zip-fil: agent.yml och skript (.sh, .ps1 eller .py). Se agent.yml och exemplen för Windows och Linux.
Öppna Agenter › Katalog och slå på Tillåt anpassade agenter under Anpassade agenter.
Välj filen under Zip-fil med agenten och klicka på Ladda upp och godkänn.
Använd agenten i en regel: i regelns steg Sammanfattning har varje tjänst en Agentkedja för …. Vilken tjänst ni väljer på en server där discovery inte känner till applikationen står i Servrar som sslbrain inte känner till. Klicka på Lägg till agent, välj er anpassade agent under Kompatibla agenter och välj åtgärden. Parametrarna från agent.yml fylls i på steget.
Är målet en server med serviceagent måste agenten ha tillåtelse att köra anpassade skript (skriptpolicy).

Stänger ni av Tillåt anpassade agenter går det inte att ladda upp nya, men de anpassade agenter som redan är godkända fortsätter att köra.

Zip-filen får vara högst 1 MB, ha 64 filer, 512 kB per fil och 4 MB uppackad. Tillåtna filtyper är yml, yaml, sh, ps1, py, json, md och txt. Dolda filer, symboliska länkar, binära filer, absoluta sökvägar och .. avvisas.

agent.yml

agent.yml beskriver agenten och dess åtgärder. Appliancen avvisar agenten om något av de här kraven inte är uppfyllt:

agent.channel är ifyllt: push-winrm för Windows och push-ssh för Linux. På en Windows-server körs skriptet genom serviceagenten, oavsett kanalens namn.
agent.tier är custom.
agent.name används inte av ett paket från FairSSL eller av ett inbyggt paket.
Varje åtgärd har runtime.location: target, en runtime.interpreter och ett runtime.delivery.mode som passar kanalen: winrm-stream för push-winrm, stdin eller scp-tmp för push-ssh.
Varje åtgärds script är en .sh-, .ps1- eller .py-fil i zip-filen.

Fält	Betydelse
`agent.channel`	`push-winrm` för Windows, `push-ssh` för Linux
`actions.<namn>`	Åtgärden, till exempel `deploy`
`runtime.interpreter`	`powershell` eller `bash`
`runtime.delivery.mode`	`winrm-stream` för Windows, `stdin` för Linux
`category`	`write` för en åtgärd som ändrar något, `read` för en som bara läser
`timeout`	Sekunder som åtgärden får köra
`cert_format`	`pem` eller `pfx_base64`: den form certifikatet ska levereras i (variabler)
`parameters`	Egna fält som fylls i i regeln

Eget skript på en Windows-server

Skriptet körs i PowerShell på servern, genom serviceagenten. Exemplet importerar certifikatet i datorns certifikatarkiv och startar om en tjänst.

agent.yml:

agent:
  name: intranet-app-windows
  display_name: "Intranet-app"
  version: "1.0.0"
  tier: custom
  description: "Installerar certifikatet för intranätappen"
  channel: push-winrm

actions:
  deploy:
    description: "Importera certifikatet och starta om tjänsten"
    script: deploy.ps1
    runtime:
      location: target
      interpreter: powershell
      delivery:
        mode: winrm-stream
    category: write
    timeout: 180
    cert_format: pfx_base64

deploy.ps1:

$ErrorActionPreference = 'Stop'
try {
    $flags = [Security.Cryptography.X509Certificates.X509KeyStorageFlags]'MachineKeySet,PersistKeySet'
    $cert = [Security.Cryptography.X509Certificates.X509Certificate2]::new(
        [Convert]::FromBase64String($PFX_BASE64), $PFX_PASSWORD, $flags)
    $store = [Security.Cryptography.X509Certificates.X509Store]::new('My', 'LocalMachine')
    $store.Open('ReadWrite'); $store.Add($cert); $store.Close()

    # Bind certifikatet till tjänsten här, till exempel med $cert.Thumbprint
    Restart-Service -Name 'IntranetApp'

    @{ status = 'success'; message = "Installerat $($cert.Thumbprint)" } | ConvertTo-Json -Compress
} catch {
    @{ status = 'error'; message = $_.Exception.Message } | ConvertTo-Json -Compress
    exit 1
}

Eget skript på en Linux-server

Skriptet körs i bash på servern. Exemplet skriver certifikat och nyckel till filer och läser om en tjänst.

agent.yml:

agent:
  name: intranet-app-linux
  display_name: "Intranet-app"
  version: "1.0.0"
  tier: custom
  description: "Installerar certifikatet för intranätappen"
  channel: push-ssh

actions:
  deploy:
    description: "Skriv certifikat och nyckel och läs om tjänsten"
    script: deploy.sh
    runtime:
      location: target
      interpreter: bash
      delivery:
        mode: stdin
    category: write
    timeout: 120
    cert_format: pem

deploy.sh:

#!/usr/bin/env bash
set -euo pipefail
trap 'echo "{\"status\":\"error\",\"message\":\"deploy misslyckades\"}"; exit 1' ERR

SUDO=""
[ "${SSLBRAIN_ELEVATE:-}" = "sudo" ] && SUDO="sudo -n"
umask 077

$SUDO mkdir -p /etc/intranet-app/tls
printf '%s\n' "$CERT_PEM" | $SUDO tee /etc/intranet-app/tls/cert.pem >/dev/null
printf '%s\n' "$KEY_PEM"  | $SUDO tee /etc/intranet-app/tls/key.pem  >/dev/null
$SUDO systemctl reload intranet-app

echo '{"status":"success"}'

SSLBRAIN_ELEVATE är satt till sudo när åtkomstuppgiften har Höj behörighet med sudo påslaget.

Vad skriptet får

Certifikatet levereras i den form som åtgärdens cert_format anger:

`cert_format`	Variabler
`pem`	`CERT_PEM`, `KEY_PEM`, och `CHAIN_PEM` när kedjan levereras separat
`pfx_base64`	`PFX_BASE64`, `PFX_PASSWORD`, `PFX_ENCRYPTION` och `CERT_PEM`

En åtgärd som deklarerar parametrarna CERT_PEM, KEY_PEM eller CHAIN_PEM utan cert_format får certifikatet som PEM.

Dessutom får skriptet alltid:

Variabler	Innehåll
`HOSTNAME`, `HOST`, `SERVER_IP`, `SERVER_OS_TYPE`	Servern
`CREDENTIAL_USER`, `CREDENTIAL_SECRET`	Åtkomstuppgiften på servern, när den har en
`SSLBRAIN_ELEVATE`	`sudo`, när autentiseringsuppgiften har Höj behörighet med sudo påslaget
`CERTIFICATE_CN`, `CERTIFICATE_SERIAL`, `CERTIFICATE_FINGERPRINT_SHA256`, `CERTIFICATE_NOT_AFTER`, `CERTIFICATE_ISSUER`, `NEW_THUMBPRINT`, `NEW_FRIENDLY_NAME`	Det certifikat som installeras
`OLD_THUMBPRINT`, `OLD_FRIENDLY_NAME`, `OLD_FINGERPRINT_SHA256`, `OLD_CERTIFICATE_SERIAL`	Det certifikat som ersätts
`ENDPOINT_NAME`, `ENDPOINT_AGENT_TYPE`, `DEPLOYMENT_MODE`	Tjänsten i regeln
`CERT_PATH`, `KEY_PATH`, `CHAIN_PATH`, `RELOAD_COMMAND`, `INIT_SYSTEM`, `SOFTWARE_VERSION`	Det som discovery har hittat på tjänsten, när det har hittats

En parameter med source: certificate.pem, certificate.key, certificate.chain, certificate.pfx_base64, certificate.pfx_password, certificate.thumbprint, certificate.previous_thumbprint eller certificate.fingerprint_sha256 får värdet under parameterns eget namn. Det är användbart i PowerShell, där variablerna också binds till param() efter namn.

I bash är värdena miljövariabler. I PowerShell är de variabler i sessionen, till exempel $PFX_BASE64.

Resultat: skriptet skriver ett JSON-objekt med status satt till success eller error och eventuellt message. Det sista objektet med status gäller. error får åtgärden att misslyckas även om exit-koden är 0, och en exit-kod som inte är 0 får den att misslyckas. Skriv alltid JSON-resultatet.

Serviceagentens skriptpolicy

Serviceagenten på servern avgör själv vilka skript den kör. Standard är FairSSL:s paket och community-paketen, inte anpassade agenter. Appliancen kan inte ändra det.

Policyn är ett tal, summan av det agenten får köra:

Värde	Får köra
1	FairSSL-paket som läser
2	FairSSL-paket som skriver
4	Community-paket som läser
8	Community-paket som skriver
16	Anpassade agenter

Standard är 15. För att köra anpassade agenter måste värdet vara 31. På en Windows-server sätts det på ett av två sätt:

Vid installationen med MSI-egenskapen SCRIPTPOLICY=31 (tyst installation).
Med Group Policy: värdet ScriptPolicy (REG_DWORD, 31) under HKLM\SOFTWARE\Policies\SSLBrain. Det går före värdet från installationen. Agenten läser om sin konfiguration under sin cykel; starta om tjänsten SSLBrainAgent om värdet ska gälla direkt.

Utan serviceagent finns ingen skriptpolicy på servern. Sidan Policy och revision › Skriptpolicy på appliancen avgör inte vad agenterna kör (policy).

Signering

Varje paket från FairSSL har ett signerat manifest med SHA-384 för varje fil och dess kategori, typ och sökväg. Signaturen är ECDSA P-384 och görs på en hårdvarunyckel hos FairSSL, aldrig i en build-pipeline. Appliancen litar bara på FairSSL:s fasta nycklar för produktion.

En anpassad agent signeras av appliancen med dess egen nyckel när den laddas upp. Serviceagenterna får appliancens nyckel när de registreras och litar på den för anpassade agenter.

Agenter › Katalog visar för varje version om signaturen är Signatur OK, Ogiltig signatur eller Ej signerad.