Egna integrationer

Ladda upp ert eget skript som en integration och använd det i en installationsplan.

Det här behöver ni

En inloggning med rollen Owner på appliancen.
agent.yml och ett skript för tjänsten. Se exemplen för Windows och Linux.
En server med serviceagent och administratörsåtkomst för att tillåta er integration.

Ladda upp integrationen

Packa agent.yml och skriptet (.sh, .ps1 eller .py) i en ZIP-fil.
Öppna Appliance › Integrationer › Katalog, slå på uppladdning av egna integrationer, välj ZIP-filen och klicka på Ladda upp och godkänn.
Öppna serverns sida. Under Egna skript klickar ni på Tillåt egna skript och anger en administratörsinloggning för den här körningen.
Välj integrationen och åtgärden under Avancerat i installationsplanens steg Kontrollera. Se valet av tjänst.

Kontrollera att det fungerar

Serverns Egna skript visar Tillåtet. I katalogen visar integrationens version Signatur OK. Skriptet ska returnera status: success när installationen lyckas.

Om det inte fungerar

ZIP-filen avvisas → jämför den med kraven på agent.yml och filgränserna nedan.
Licensen saknar plats → Free tillåter 1 egen integration, Basic 3. Professional och Enterprise har ingen gräns i licensen. En version av en befintlig integration tar ingen extra plats.
Servern avvisar signeringsnyckeln → kontrollera tillåtelsen på servern. Integrationer får bara köras där servern litar på appliancens nyckel.
Skriptet returnerar error → läs message i resultatet, rätta skriptet och ladda upp en version med rättelsen.

Tillåt integrationen på servern

En egen integration körs på målservern, aldrig på appliancen. Den kan inte anropa ett API från appliancen. På en server med serviceagent kräver tillåtelsen Windows-serviceagent 1.5.0 eller Linux-serviceagent 0.7.0 eller senare. Appliancen ändrar tillåtelsen via WinRM eller SSH och startar om serviceagenten.

Vid installation kan ni markera Tillåt egna skript från den här appliancen under Servrar › Lägg till server › Med serviceagent. På en registrerad server använder ni Egna skript. Sidan visar tillåtelsen, tidpunkten och vem som ändrade den. Varje ändring loggas. En uppdatering av serviceagenten ändrar inte tillåtelsen.

Använd en administratörsinloggning för den enskilda körningen. En sparad administratörsinloggning kan missbrukas om appliancen eller dess administratörskonton komprometteras.

Stänger ni av uppladdning av egna integrationer i katalogen fortsätter de godkända att köra. Stänger ni av tillåtelsen på servern tas tilliten till den här appliancens nyckel bort. Andra betrodda nycklar bevaras.

En ScriptPolicy från Group Policy bestämmer fortfarande vad som får köras. Värdet 0 blockerar allt, även signerade integrationer från FairSSL. Värdena finns under Policy och revision.

För hand

Öppna Appliance › Integrationer › Katalog. Appliancens signeringsnyckel visar ett fingeravtryck som sha256:<64 hex>. För Linux hämtar ni filen sslbrain-appliance-signing-key.pem med knappen för att hämta den offentliga nyckeln till Linux-serviceagenten.

Windows

Lägg till fingeravtrycket i Custom som REG_MULTI_SZ med ett fingeravtryck per rad och sätt AllowCustomAgentsFrom till local. Bevara andra nycklar och källor om värdena redan finns. Exemplet gäller en server utan dessa värden. Kör som administratör och ersätt <fingerprint> med de 64 hextecknen:

reg add "HKLM\SOFTWARE\sslbrain\TrustedKeys" /v Custom /t REG_MULTI_SZ /d "sha256:<fingerprint>" /f
reg add "HKLM\SOFTWARE\sslbrain" /v AllowCustomAgentsFrom /t REG_SZ /d "local" /f
Restart-Service sslbrainagent

Vid installationen kan ni använda ALLOW_CUSTOM_AGENTS_FROM=LOCAL TRUSTEDKEYS_CUSTOM="sha256:<fingerprint>". TRUSTEDKEYS_CUSTOM fyller bara i Custom när värdet saknas eller är tomt (MSI-egenskaper).

Linux

Kopiera den hämtade PEM-filen till servern. Lägg den på den fasta sökvägen:

sudo install -m 0644 sslbrain-appliance-signing-key.pem /var/lib/sslbrain/state/appliance-signing-key.pem

Sätt denna rad i /etc/sslbrain/agent.conf:

ALLOW_CUSTOM_AGENTS_FROM=APPLIANCE

Starta om serviceagenten:

sudo systemctl restart sslbrain-agent.service

Utan nyckelfilen eller inställningen avvisar serviceagenten den egna integrationen på grund av en obetrodd nyckel utan att köra den.

Värdet är summan av det serviceagenten får köra:

Värde	Får köra
1	Integrationer från FairSSL som läser
2	Integrationer från FairSSL som skriver
4	Integrationer från andra som läser
8	Integrationer från andra som skriver
16	Egna integrationer

Värdena 4 och 8 gäller integrationer från andra. Katalogens integrationer är skrivna, granskade och signerade av FairSSL.

Sidan Appliance › Integrationer › Godkännande på appliancen avgör inte vad serviceagenterna kör (policy).

agent.yml

Appliancen avvisar integrationen om något av fälten saknas eller inte stämmer:

Fält	Värde
`agent.name`	Ett namn som ingen integration från FairSSL och ingen inbyggd integration använder
`agent.tier`	`custom`
`agent.channel`	`push-ssh` när appliancen kör skriptet via SSH på en server utan serviceagent, eller `pull-service-agent`. På en server med en registrerad serviceagent körs åtgärden alltid genom serviceagenten, oavsett kanal
`actions.<namn>`	Åtgärden, till exempel `deploy`
`script`	En `.sh`-, `.ps1`- eller `.py`-fil i zip-filen
`shell`	På varje åtgärd: `bash` för Linux eller `powershell` för Windows. Serviceagenten kör bara rätt skal för serverns operativsystem
`runtime.location`	`target`
`runtime.interpreter`	`bash` för Linux eller `powershell` för Windows
`runtime.delivery.mode`	`stdin` eller `scp-tmp` för `push-ssh`, `none` för `pull-service-agent`
`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` (variabler)
`parameters`	De indata som skriptet får. På en serviceagent är det de enda

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.

Zip-filen får inte innehålla agent-manifest eller agent-manifest.sig. Appliancen signerar själv vid uppladdningen.

Windows-servrar

På Windows-servrar installerar sslbrain certifikat genom serviceagenten. Använd helst de signerade integrationerna i katalogen för IIS, Exchange, SQL Server och Windows certifikatarkiv (Integrationer). Så installeras serviceagenten: Windows-servrar.

För er egen tjänst kan ni använda detta exempel. Det importerar certifikatet till Cert:\LocalMachine\My. Anpassa skriptet om tjänsten också behöver få certifikatet kopplat eller startas om. Lita på appliancens nyckel och tillåt egna integrationer först.

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: pull-service-agent
  compatibility:
    os: ["Windows"]

actions:
  deploy:
    description: "Importera certifikatet till Windows certifikatarkiv"
    script: deploy.ps1
    shell: powershell
    runtime:
      location: target
      interpreter: powershell
      delivery:
        mode: none
    category: write
    timeout: 120
    cert_format: pfx_base64
    parameters:
      PFX_BASE64:
        type: string
        required: true
        secret: true
        source: certificate.pfx_base64
        encoding: base64
        content: opaque
        max_decoded_bytes: 48000
        validation: '^[A-Za-z0-9+/=\x09-\x0d ]+$'
      PFX_PASSWORD:
        type: string
        required: true
        secret: true
        source: certificate.pfx_password
        validation: "^[^\\x00-\\x08\\x0a-\\x1f]{1,1000}$"

deploy.ps1:

param([string]$PFX_BASE64, [string]$PFX_PASSWORD)

$ErrorActionPreference = 'Stop'
$tempFile = $null
try {
    $tempFile = [System.IO.Path]::GetTempFileName()
    [System.IO.File]::WriteAllBytes($tempFile, [Convert]::FromBase64String($PFX_BASE64))
    Import-PfxCertificate -FilePath $tempFile -CertStoreLocation Cert:\LocalMachine\My `
        -Password (ConvertTo-SecureString $PFX_PASSWORD -AsPlainText -Force) | Out-Null
    Write-Output '{"status":"success"}'
} catch {
    @{ status = 'error'; message = $_.Exception.Message } | ConvertTo-Json -Compress
    exit 1
} finally {
    if ($tempFile) {
        Remove-Item -LiteralPath $tempFile -Force
    }
}

Eget skript på en Linux-server

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
    shell: bash
    runtime:
      location: target
      interpreter: bash
      delivery:
        mode: stdin
    category: write
    timeout: 120
    cert_format: pem
    parameters:
      CERT_PEM:
        type: string
        required: true
        secret: true
        source: certificate.pem
        encoding: base64
        content: opaque
        max_decoded_bytes: 48000
        validation: "[A-Za-z0-9+/]+={0,2}"
      KEY_PEM:
        type: string
        required: true
        secret: true
        source: certificate.key
        encoding: base64
        content: opaque
        max_decoded_bytes: 48000
        validation: "[A-Za-z0-9+/]+={0,2}"

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' "$CERT_PEM" | base64 -d | $SUDO tee /etc/intranet-app/tls/cert.pem >/dev/null
printf '%s' "$KEY_PEM"  | base64 -d | $SUDO tee /etc/intranet-app/tls/key.pem  >/dev/null
$SUDO systemctl reload intranet-app

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

Vad skriptet får

En certifikatkedja är de mellanliggande certifikat som förbinder serverns certifikat med en rot som webbläsaren litar på.

Skriptet får de parametrar som åtgärden deklarerar under parameters, under parameterns eget namn. På en server med en serviceagent får skriptet inga andra värden.

I bash är värdena variabler i skriptet, till exempel $CERT_PEM. På en serviceagent exporteras de inte till program som skriptet startar. I PowerShell binds de till skriptets param() efter namn. På en serviceagent är det den enda vägen in, så deklarera dem i param() som i exemplet.

Ange certifikatet 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 binära data eller PEM ska parametern också ha encoding: base64. Värdet kommer då base64-kodat, och skriptet avkodar det som i exemplen ovan.

Åtgärdens cert_format väljer certifikatets form. Värdena når skriptet bara genom deklarerade parametrar. Utan cert_format får en åtgärd som deklarerar CERT_PEM, KEY_PEM eller CHAIN_PEM certifikatet som PEM.

`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`

Ett skript som körs över SSH (kanalen push-ssh, server utan serviceagent) får också värdena nedan. På en serviceagent får skriptet dem bara om åtgärden deklarerar dem som parametrar:

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 åtkomstuppgiften har Höj behörighet med sudo påslaget. En serviceagent kör åtgärden som root och sätter den aldrig
`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 installationsplanen
`CERT_PATH`, `KEY_PATH`, `CHAIN_PATH`, `RELOAD_COMMAND`, `INIT_SYSTEM`, `SOFTWARE_VERSION`	Det som discovery har hittat på tjänsten

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

Signering

Appliancen signerar en egen integration med sin egen ECDSA P-256-nyckel när den laddas upp. Serviceagenten kör bara integrationen när ni har gjort nyckeln betrodd på servern och tillåtit egna integrationer som beskrivs ovan.

Integrationer från FairSSL har ett manifest med SHA-384 för varje fil, signerat med ECDSA P-384 på en hårdvarunyckel hos FairSSL. Appliancen litar bara på FairSSL:s fasta nycklar för produktion.

Appliance › Integrationer › Katalog visar för varje version Signatur OK, Ogiltig signatur eller Ej signerad.