Egne scripts

Til en platform, kataloget ikke dækker, skriver I selv scriptet og lægger det op som en custom agent under Agenter › Katalog. Appliancen signerer det med sin egen nøgle, og det kører kun på målserveren, aldrig på appliancen.

Læg en custom agent op

Kun en Owner kan slå custom agenter til og lægge dem op.
Licensen bestemmer, hvor mange custom agenter appliancen kan have: Free 1, Basic 3, Professional og Enterprise ubegrænset. En ny version af en custom agent, I har, tager ikke en plads mere.
En custom agent kan ikke kalde et API fra appliancen. Alle handlinger kører på målserveren.

Pak agenten som en zip-fil: agent.yml og scripts (.sh, .ps1 eller .py). Se agent.yml og eksemplerne til Windows og Linux.
Åbn Agenter › Katalog, og slå Tillad custom agenter til under Custom agenter.
Vælg filen under Zip-fil med agenten, og klik på Upload og godkend.
Brug agenten i en regel: i reglens trin Opsummering har hver tjeneste en Agentkæde for …. Hvilken tjeneste I vælger på en server, som discovery ikke kender applikationen på, står i Servere, sslbrain ikke kender. Klik på Tilføj agent, vælg jeres custom agent under Kompatible agenter, og vælg handlingen. Parametrene fra agent.yml udfyldes på trinnet.
Er målet en server med service-agent, skal agenten have lov til at køre custom scripts (script-politik).

Slår I Tillad custom agenter fra, kan der ikke lægges nye op, men de custom agenter, der allerede er godkendt, kører videre.

Zip-filen må højst fylde 1 MB, have 64 filer, 512 KB pr. fil og 4 MB udpakket. Tilladte filtyper er yml, yaml, sh, ps1, py, json, md og txt. Skjulte filer, symbolske links, binære filer, absolutte stier og .. afvises.

agent.yml

agent.yml beskriver agenten og dens handlinger. Appliancen afviser agenten, hvis et af disse krav ikke er opfyldt:

agent.channel er udfyldt: push-winrm til Windows og push-ssh til Linux. På en Windows-server kører scriptet gennem service-agenten, uanset kanalens navn.
agent.tier er custom.
agent.name bruges ikke af en pakke fra FairSSL eller af en indbygget pakke.
Hver handling har runtime.location: target, en runtime.interpreter og en runtime.delivery.mode, der passer til kanalen: winrm-stream til push-winrm, stdin eller scp-tmp til push-ssh.
Hver handlings script er en .sh-, .ps1- eller .py-fil i zip-filen.

Felt	Betydning
`agent.channel`	`push-winrm` til Windows, `push-ssh` til Linux
`actions.<navn>`	Handlingen, fx `deploy`
`runtime.interpreter`	`powershell` eller `bash`
`runtime.delivery.mode`	`winrm-stream` til Windows, `stdin` til Linux
`category`	`write` for en handling, der ændrer noget, `read` for en, der kun læser
`timeout`	Sekunder, handlingen må køre
`cert_format`	`pem` eller `pfx_base64`: den form, certifikatet skal leveres i (variabler)
`parameters`	Egne felter, der udfyldes i reglen

Eget script på en Windows-server

Scriptet kører i PowerShell på serveren, gennem service-agenten. Eksemplet importerer certifikatet i computerens certifikatlager og genstarter en tjeneste.

agent.yml:

agent:
  name: intranet-app-windows
  display_name: "Intranet-app"
  version: "1.0.0"
  tier: custom
  description: "Installerer certifikatet til intranet-appen"
  channel: push-winrm

actions:
  deploy:
    description: "Importér certifikatet og genstart tjenesten"
    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 til tjenesten her, fx med $cert.Thumbprint
    Restart-Service -Name 'IntranetApp'

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

Eget script på en Linux-server

Scriptet kører i bash på serveren. Eksemplet skriver certifikat og nøgle til filer og genindlæser en tjeneste.

agent.yml:

agent:
  name: intranet-app-linux
  display_name: "Intranet-app"
  version: "1.0.0"
  tier: custom
  description: "Installerer certifikatet til intranet-appen"
  channel: push-ssh

actions:
  deploy:
    description: "Skriv certifikat og nøgle, og genindlæs tjenesten"
    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 fejlede\"}"; 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 er sat til sudo, når adgangen har Løft rettigheder med sudo slået til.

Hvad scriptet får

Certifikatet leveres i den form, handlingens cert_format angiver:

`cert_format`	Variabler
`pem`	`CERT_PEM`, `KEY_PEM`, og `CHAIN_PEM`, når kæden leveres for sig
`pfx_base64`	`PFX_BASE64`, `PFX_PASSWORD`, `PFX_ENCRYPTION` og `CERT_PEM`

En handling, der erklærer parametrene CERT_PEM, KEY_PEM eller CHAIN_PEM uden cert_format, får certifikatet som PEM.

Desuden får scriptet altid:

Variabler	Indhold
`HOSTNAME`, `HOST`, `SERVER_IP`, `SERVER_OS_TYPE`	Serveren
`CREDENTIAL_USER`, `CREDENTIAL_SECRET`	Adgangen på serveren, når den har en
`SSLBRAIN_ELEVATE`	`sudo`, når adgangsoplysningen har Løft rettigheder med sudo slået til
`CERTIFICATE_CN`, `CERTIFICATE_SERIAL`, `CERTIFICATE_FINGERPRINT_SHA256`, `CERTIFICATE_NOT_AFTER`, `CERTIFICATE_ISSUER`, `NEW_THUMBPRINT`, `NEW_FRIENDLY_NAME`	Det nye certifikat
`OLD_THUMBPRINT`, `OLD_FRIENDLY_NAME`, `OLD_FINGERPRINT_SHA256`, `OLD_CERTIFICATE_SERIAL`	Det certifikat, der erstattes
`ENDPOINT_NAME`, `ENDPOINT_AGENT_TYPE`, `DEPLOYMENT_MODE`	Tjenesten i reglen
`CERT_PATH`, `KEY_PATH`, `CHAIN_PATH`, `RELOAD_COMMAND`, `INIT_SYSTEM`, `SOFTWARE_VERSION`	Det, discovery har fundet på tjenesten, når det er fundet

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ærdien under parameterens eget navn. Det er nyttigt i PowerShell, hvor variablerne også bindes til param() efter navn.

I bash er værdierne miljøvariabler. I PowerShell er de variabler i sessionen, fx $PFX_BASE64.

Resultat: scriptet skriver et JSON-objekt med status sat til success eller error og eventuelt message. Det sidste objekt med status gælder. error får handlingen til at fejle, også hvis exit-koden er 0, og en exit-kode, der ikke er 0, får den til at fejle. Skriv altid JSON-resultatet.

Service-agentens script-politik

Service-agenten på serveren bestemmer selv, hvilke scripts den kører. Standard er FairSSL’s og community-pakkerne, ikke custom agenter. Appliancen kan ikke ændre det.

Politikken er et tal, summen af det, agenten må køre:

Værdi	Må køre
1	FairSSL-pakker, der læser
2	FairSSL-pakker, der skriver
4	Community-pakker, der læser
8	Community-pakker, der skriver
16	Custom agenter

Standard er 15. For at køre custom agenter skal værdien være 31. På en Windows-server sættes den på en af to måder:

Ved installation med MSI-egenskaben SCRIPTPOLICY=31 (stille installation).
Med Group Policy: værdien ScriptPolicy (REG_DWORD, 31) under HKLM\SOFTWARE\Policies\SSLBrain. Den går forud for værdien fra installationen. Agenten læser sin konfiguration igen i løbet af sin cyklus; genstart tjenesten SSLBrainAgent, hvis værdien skal gælde med det samme.

Uden service-agent er der ingen script-politik på serveren. Siden Politik og revision › Script-politik på appliancen bestemmer ikke, hvad agenterne kører (politik).

Signering

Hver pakke fra FairSSL har et signeret manifest med SHA-384 af hver fil og dens kategori, type og sti. Signaturen er ECDSA P-384 og laves på en hardware-nøgle hos FairSSL, aldrig i en build-pipeline. Appliancen stoler kun på FairSSL’s faste nøgler til produktion.

En custom agent signeres af appliancen med dens egen nøgle, når den lægges op. Service-agenterne får appliancens nøgle, når de registreres, og stoler på den til custom agenter.

Agenter › Katalog viser for hver version, om signaturen er Signatur OK, Ugyldig signatur eller Ikke signeret.