Egne integrationer

Læg jeres eget script op som en integration, og brug det i en installationsplan.

Det skal I bruge

Et login med rollen Owner på appliancen.
agent.yml og et script til tjenesten. Se eksemplerne til Windows og Linux.
En server med service-agent og administratoradgang til at tillade jeres integration.

Læg integrationen op

Pak agent.yml og scriptet (.sh, .ps1 eller .py) i en ZIP-fil.
Åbn Appliance › Integrationer › Katalog, slå upload af egne integrationer til, vælg ZIP-filen, og klik på Upload og godkend.
Åbn serverens side. Under Egne scripts klikker I på Tillad egne scripts og indtaster et administratorlogin til denne kørsel.
Vælg integrationen og handlingen under Avanceret i installationsplanens trin Kontrollér. Se valget af tjeneste.

Kontrollér, at det virker

Serverens Egne scripts viser Tilladt. I kataloget viser integrationens version Signatur OK. Scriptet skal returnere status: success, når installationen lykkes.

Hvis det fejler

ZIP-filen afvises → sammenlign den med kravene til agent.yml og filgrænserne nedenfor.
Licensen har ikke plads → Free tillader 1 egen integration, Basic 3. Professional og Enterprise har ingen grænse i licensen. En version af en eksisterende integration tager ikke en ekstra plads.
Serveren afviser signeringsnøglen → kontrollér tilladelsen på serveren. Integrationer må kun køre, hvor serveren stoler på appliancens nøgle.
Scriptet returnerer error → læs message i resultatet, ret scriptet, og upload en version med rettelsen.

Tillad integrationen på serveren

En egen integration kører på målserveren, aldrig på appliancen. Den kan ikke kalde et API fra appliancen. På en server med service-agent kræver tilladelsen Windows-service-agent 1.5.0 eller Linux-service-agent 0.7.0 eller senere. Appliancen ændrer tilladelsen over WinRM eller SSH og genstarter service-agenten.

Ved installation kan I sætte Tillad egne scripts fra denne appliance under Servere › Tilføj server › Med service-agent. På en registreret server bruger I Egne scripts. Siden viser tilladelsen, tidspunktet og den, der ændrede den. Hver ændring logges. En opdatering af service-agenten ændrer ikke tilladelsen.

Brug et administratorlogin til den enkelte kørsel. Et gemt administratorlogin kan udnyttes, hvis appliancen eller dens administratorkonti bliver kompromitteret.

Slår I upload af egne integrationer fra i kataloget, kører de godkendte videre. Slår I tilladelsen fra på serveren, fjernes tilliden til denne appliances nøgle. Andre betroede nøgler bevares.

En ScriptPolicy fra Group Policy bestemmer stadig, hvad der må køre. Værdien 0 blokerer alt, også signerede integrationer fra FairSSL. Værdierne står under Politik og revision.

I hånden

Åbn Appliance › Integrationer › Katalog. Appliancens signeringsnøgle viser et fingeraftryk som sha256:<64 hex>. Til Linux henter I filen sslbrain-appliance-signing-key.pem via Hent offentlig nøgle til Linux-service-agenten (PEM).

Windows

Tilføj fingeraftrykket i Custom som REG_MULTI_SZ med ét fingeraftryk pr. linje, og sæt AllowCustomAgentsFrom til local. Bevar andre nøgler og kilder, hvis værdierne allerede findes. Eksemplet er til en server uden disse værdier. Kør som administrator, og erstat <fingerprint> med de 64 hextegn:

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

Ved installationen kan I bruge ALLOW_CUSTOM_AGENTS_FROM=LOCAL TRUSTEDKEYS_CUSTOM="sha256:<fingerprint>". TRUSTEDKEYS_CUSTOM udfylder kun Custom, når værdien mangler eller er tom (MSI-egenskaber).

Linux

Kopiér den hentede PEM-fil til serveren. Læg den på den faste sti:

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

Sæt denne linje i /etc/sslbrain/agent.conf:

ALLOW_CUSTOM_AGENTS_FROM=APPLIANCE

Genstart service-agenten:

sudo systemctl restart sslbrain-agent.service

Uden nøglefilen eller indstillingen afviser service-agenten integrationen med en fejl om en nøgle, den ikke stoler på. Scriptet kører ikke.

Værdien er summen af det, service-agenten må køre:

Værdi	Må køre
1	Integrationer fra FairSSL, der læser
2	Integrationer fra FairSSL, der skriver
4	Integrationer fra andre, der læser
8	Integrationer fra andre, der skriver
16	Egne integrationer

Værdierne 4 og 8 gælder integrationer fra andre. Katalogets integrationer er skrevet, gennemgået og signeret af FairSSL.

Siden Appliance › Integrationer › Godkendelse på appliancen bestemmer ikke, hvad service-agenterne kører (politik).

agent.yml

Appliancen afviser integrationen, hvis et af felterne mangler eller ikke passer:

Felt	Værdi
`agent.name`	Et navn, som ingen integration fra FairSSL eller indbygget integration bruger
`agent.tier`	`custom`
`agent.channel`	`push-ssh`, når appliancen kører scriptet over SSH på en server uden service-agent, eller `pull-service-agent`. På en server med en registreret service-agent kører handlingen altid gennem service-agenten, uanset kanal
`actions.<navn>`	Handlingen, fx `deploy`
`script`	En `.sh`-, `.ps1`- eller `.py`-fil i zip-filen
`shell`	På hver handling: `bash` til Linux eller `powershell` til Windows. Service-agenten kører kun den shell, der passer til serverens operativsystem
`runtime.location`	`target`
`runtime.interpreter`	`bash` til Linux eller `powershell` til Windows
`runtime.delivery.mode`	`stdin` eller `scp-tmp` til `push-ssh`, `none` til `pull-service-agent`
`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` (variabler)
`parameters`	De input, scriptet får. På en service-agent er det de eneste

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.

Zip-filen må ikke indeholde agent-manifest eller agent-manifest.sig. Appliancen signerer selv ved upload.

Windows-servere

På Windows-servere installerer sslbrain certifikater gennem service-agenten. Brug helst de signerede integrationer i kataloget til IIS, Exchange, SQL Server og Windows’ certifikatlager (Integrationer). Sådan installeres service-agenten: Windows-servere.

Til jeres egen tjeneste kan I bruge dette eksempel. Det importerer certifikatet i Cert:\LocalMachine\My. Tilpas scriptet, hvis tjenesten også skal have certifikatet tilknyttet eller genstartes. Stol på appliancens nøgle, og tillad egne integrationer først.

agent.yml:

agent:
  name: intranet-app-windows
  display_name: "Intranet-app"
  version: "1.0.0"
  tier: custom
  description: "Installerer certifikatet til intranet-appen"
  channel: pull-service-agent
  compatibility:
    os: ["Windows"]

actions:
  deploy:
    description: "Importér certifikatet i Windows' certifikatlager"
    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 script på en Linux-server

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
    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 fejlede\"}"; 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"}'

Hvad scriptet får

En certifikatkæde er de mellemliggende certifikater, der forbinder serverens certifikat med en rod, browseren stoler på.

Scriptet får de parametre, handlingen erklærer under parameters, under parameterens eget navn. På en server med en service-agent får scriptet ikke andre værdier.

I bash er værdierne variabler i scriptet, fx $CERT_PEM. På en service-agent eksporteres de ikke til programmer, scriptet starter. I PowerShell bindes de til scriptets param() efter navn. På en service-agent er det den eneste vej ind, så erklær dem i param() som i eksemplet.

Angiv certifikatet med source: certificate.pem, certificate.key, certificate.chain, certificate.pfx_base64, certificate.pfx_password, certificate.thumbprint, certificate.previous_thumbprint eller certificate.fingerprint_sha256. For binære data eller PEM skal parameteren også have encoding: base64. Værdien kommer så base64-kodet, og scriptet afkoder den som i eksemplerne ovenfor.

Handlingens cert_format vælger certifikatets form. Værdierne når kun scriptet gennem erklærede parametre. Uden cert_format får en handling, der erklærer CERT_PEM, KEY_PEM eller CHAIN_PEM, certifikatet som PEM.

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

Et script, der køres over SSH (kanalen push-ssh, server uden service-agent), får også værdierne nedenfor. På en service-agent får scriptet dem kun, hvis handlingen erklærer dem som parametre:

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 adgangen har Løft rettigheder med sudo slået til. En service-agent kører handlingen som root og sætter den aldrig
`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 installationsplanen
`CERT_PATH`, `KEY_PATH`, `CHAIN_PATH`, `RELOAD_COMMAND`, `INIT_SYSTEM`, `SOFTWARE_VERSION`	Det, discovery har fundet på tjenesten

Resultat: scriptet skriver altid et JSON-objekt med status sat til success eller error og eventuelt message. Det sidste objekt med status gælder. Handlingen fejler ved error, også hvis exit-koden er 0, og ved en exit-kode, der ikke er 0.

Signering

Appliancen signerer jeres egen integration med sin egen ECDSA P-256-nøgle, når den lægges op. Service-agenten kører kun integrationen, når I har gjort nøglen betroet på serveren og tilladt egne integrationer som beskrevet ovenfor.

Integrationer fra FairSSL har et manifest med SHA-384 af hver fil, signeret med ECDSA P-384 på en hardware-nøgle hos FairSSL. Appliancen stoler kun på FairSSL’s faste nøgler til produktion.

Appliance › Integrationer › Katalog viser for hver version Signatur OK, Ugyldig signatur eller Ikke signeret.