FC Agent — private infrastructuur

De FC Agent is een kleine service die je in je eigen omgeving draait — doorgaans als één pod in je Kubernetes-cluster. Hij verbindt uitgaand met FixControl over HTTPS en voert getekende, aflopende, single-use operaties uit: een gepauzeerde CI-deployment goedkeuren of afwijzen, een gepauzeerde Argo-rollout promoten, of een validatie in je cluster draaien.

FixControl verbindt met private klantinfrastructuur via deze uitgaande agent. Kubernetes, Argo, Jenkins en GitLab hoeven niet publiek te worden blootgesteld aan FixControl.

Je installeert en beheert de agent zelf. Het installatiepakket is een openbare release — gewone Kubernetes-manifests met een gescripte installer — op github.com/FixControl-AI/fixcontrol-agent, en Instellingen → DevOps → fc-agents linkt de gepinde versie naast de agent-identiteit en de te pinnen signing keys, op het moment dat je enrolt.

Architectuur

        FixControl Cloud
        (poorten, goedkeuringen, bewijs, audit)
                 ▲
                 │  uitgaand HTTPS (geïnitieerd door de agent)
                 │
             FC Agent          ← draait in jouw omgeving
            /    |    \
           /     |     \
   Kubernetes   Argo   Jenkins / GitLab
   (privé — geen van deze wordt blootgesteld aan FixControl)

• De agent pollt FixControl met een kort, door de server geadverteerd interval. Er is geen push-kanaal, geen listener, geen inkomende socket: het manifest van de agent bevat geen Service, geen Ingress en geen inkomende network policy, en zijn health-endpoint bindt op localhost.
• FixControl registreert een operatie — het verdict van een besliste poort, of een verzoek om een validatie te draaien. De agent haalt haar op bij zijn volgende poll, verifieert lokaal, voert uit, en meldt het resultaat terug — ook uitgaand. Elk uitvoerings-verdict (goedkeuren, afwijzen, promoten) is een vastgelegde menselijke beslissing.
• Onder het agent-verbindingsmodel opent FixControl geen enkele verbinding richting je netwerk en bewaart het geen credential voor je infrastructuur.

Vereisten

• De FC Agent ingeschakeld voor je workspace. Die staat standaard uit; je FixControl-beheerder zet hem aan. Staat hij uit, dan wordt er geen operatie geregistreerd en geen agent-request geaccepteerd.
• Een Kubernetes-cluster (de agent draait als Deployment; het installatiepakket bestaat uit gewone Kubernetes-manifests gerenderd met Kustomize — geen Helm nodig).
• Uitgaand HTTPS vanuit de agent-namespace naar FixControl (doorgaans poort 443), via je bestaande egress- of proxyregels.
• De Kubernetes-integratie eerst verbonden — een agent-registratie hangt aan die verbinding, en enrolment weigert zonder.
• Een ge-enrolde agent-identiteit: aangemaakt onder Instellingen → DevOps → fc-agents (of POST /api/integrations/devops/agents). Enrolment toont het agent-secret één keer en somt de te pinnen FixControl-signing-keys op.
• De capability gearmd: agent-carriage staat uit totdat een beheerder van je organisatie Het oordeel overdragen aan een fc-agent in je cluster armt onder Instellingen → AI & goedkeuring → Goedkeuringen → Deployment-bevoegdheden. Elke deployment-bevoegdheid op die kaart staat standaard uit. Armen vraagt een reden en wordt ge-audit; ontwapenen is één klik. Tot het gearmd is, openen poorten en worden beslissingen vastgelegd, maar wordt er niets voor de agent geregistreerd.

Netwerk

De egress van de agent, volledig:

sta egress toe  agent-namespace → FixControl (HTTPS, 443)
                                   (voor de hosted dienst: api.fixcontrol.ai —
                                    het enrolment-paneel toont de exacte URL als
                                    "FixControl URL")
                agent-namespace → je manifests-git-remote
                                   (alleen met het standaard GitOps-promotiepad)
                agent-namespace → je private GitLab / Jenkins
                                   (alleen met CI-verdict-carriage)
                agent-namespace → kube-apiserver + cluster-DNS
                                   (de NetworkPolicy van de installer voegt deze
                                    zelf toe)
benodigde inkomende regels: geen

Het pipeline-event bereikt FixControl nog steeds via de eigen signed webhook van de CI-host — de agent draagt het verdict terug, niet het event naar binnen. Een private CI-host heeft dus zelf ook uitgaand HTTPS naar FixControl nodig (of een proxy die dat levert).

• De agent weigert te starten tegen een onversleutelde http://-FixControl-URL. TLS wordt geverifieerd; er is bewust geen optie om TLS-verificatie over te slaan.
• Standaard egress-proxy's werken zolang de agent de FixControl-origin kan bereiken; de operatie-handtekening dekt het request-pad, dus tussenstations kunnen een request niet ongemerkt omleiden.
• Het eigen health-/metrics-endpoint van de agent bindt op 127.0.0.1 en wordt in de pod geprobed.

Authenticatie en operatie-ondertekening

Twee onafhankelijke mechanismen, met twee onafhankelijke sleutels:

1. Transportauthenticatie — elk request van de agent draagt een HMAC-SHA256-handtekening onder het eigen per-agent-secret, plus een tijdstempel met een begrensd skew-venster. Het secret wordt één keer getoond bij enrolment, door FixControl alleen versleuteld opgeslagen, en is op elk moment te roteren of in te trekken; intrekking werkt vanaf het eerstvolgende request.
2. Operatie-autoriteit — elke operatie wordt door FixControl getekend met een Ed25519-sleutel waarvan jij de publieke helft in de configuratie van de agent pint. De agent bevat geen signing-code voor deze sleutel — hij kan operaties verifiëren, nooit zelf uitgeven. Een gepinde agent weigert operaties die anders getekend zijn, zodat de bevoegdheid om een actie op te dragen cryptografisch gescheiden is van de mogelijkheid om met de API te praten.

Levenscyclus van een operatie

Elke operatie is single-use, aflopend en idempotent:

• Vervaltijd — operaties verlopen minuten na registratie (standaard 5). Een goedkeuring van 10:00 kan nooit om 16:00 nog iets promoten omdat een agent plat lag; de verlopen operatie wordt zichtbaar als verlopen vastgelegd.
• Replay-bescherming — elke operatie draagt een willekeurige nonce. De agent houdt een persistent nonce-grootboek bij in zijn eigen namespace en weigert een nonce die hij al zag, met terugmelding en reden replay in plaats van een stille drop.
• Idempotente afhandeling — een operatie wordt één keer afgehandeld. Een strijdig tweede resultaat wordt als conflict vastgelegd en herschrijft het eerste niet.
• Geadresseerd, niet uitgezonden — een operatie noemt één cluster en één capability, en CI-verdicts zijn bovendien gepind op de specifieke agent die op de koppeling staat. De pin reist binnen de handtekening mee.

Capabilities en lokale allowlists

Het operatie-vocabulaire is gesloten: een CI-deployment goedkeuren/afwijzen, een Argo-rollout promoten/afbreken/lezen, een validatie draaien/annuleren. Er bestaat geen "voer dit commando uit"-operatie.

Wat een agent werkelijk mag uitvoeren wordt op drie plekken bepaald, en de laatste is volledig van jou:

1. De registratie in FixControl kent de agent een capability-set toe.
2. Elke poll doorsnijdt die toekenning met wat de draaiende agent adverteert — geen van beide kanten kan de andere verbreden.
3. De lokale allowlists van de agent — de namespaces waarin hij mag handelen, de rollouts die hij mag aanraken, en de set capabilities die hij aanzet — leven in de configuratie van de agent in jouw cluster (de values.env die de installer leest; de README van het pakket noemt elk onderdeel). FixControl stuurt ze nooit mee en kan ze niet overschrijven. Een lege namespace-allowlist betekent dat niets is toegestaan — de installer weigert een installatie die haar per ongeluk leeg laat.

Runner-capabilities — wat de machine echt kan draaien

De operaties van een agent (hierboven) zeggen wat hij mag. Dat is een andere vraag dan wat de machine waarop hij draait kan, en FixControl houdt die twee bewust uit elkaar.

Een runner beschrijft zichzelf: besturingssysteemfamilie, processorarchitectuur, containerruntime, de taalruntimes, compilers, buildsystemen en SDK's die hij heeft, systeembibliotheken, runtime-extensies, tools, eventuele proprietaire capability, hardware, en welke service-implementaties (of willekeurige service-images) hij kan starten. Die beschrijving komt op twee manieren binnen — geadverteerd door de draaiende agent, of verklaard door jou voor iets dat de agent-build niet kan detecteren. Een verklaring gaat boven een advertentie en wordt nooit door een poll overschreven.

Twee regels volgen daaruit, en allebei zijn het weigeringen in plaats van vervangingen:

• Geen stilzwijgende vervanging. GCC is geen MSVC, Linux is geen Windows, een opensource-compiler is geen proprietaire SDK, PHP 8.3 voldoet niet aan >=8.4. Een project waarvan de omgeving iets nodig heeft dat geen runner biedt, wordt geweigerd met de exact ontbrekende capability benoemd, per familie en per runner.
• Capability en bereikbaarheid zijn twee antwoorden. Een runner kan elke capability hebben die een project nodig heeft en toch onbruikbaar zijn omdat deze build er geen transport naartoe heeft. Je hoort welke van de twee het is — een runner zonder compiler en een runner waar FixControl geen werk naartoe kan dragen zijn verschillende problemen met verschillende oplossingen.

Een runner zonder beschrijving matcht niets. Dat is bewust: een onbeschreven runner zou anders stilzwijgend het antwoord op elke vraag worden.

Valideren op je eigen runner

Een project kan zijn wijzigingen laten valideren door een runner in jouw cluster in plaats van op de infrastructuur van FixControl, of daarnaast. Dat verplaatst de uitvoering van de build en de tests naar jouw omgeving; het verandert niet waar je broncode wordt opgeslagen — FixControl kloont de repository nog steeds op zijn eigen servers en stuurt broncode naar zijn AI-providers om eraan te werken.

Dit moet allemaal kloppen voordat een run naar je runner gaat:

• De FC Agent is ingeschakeld voor je workspace en er is een geregistreerde agent verbonden (zie Vereisten).
• De agent adverteert de capability `test.run`. Een agent die die niet aanbiedt, krijgt nooit een validatie.
• Remote validatie is toegestaan voor het project. De standaard voor de workspace staat uit, en je FixControl-beheerder wijzigt die standaard. Elk project kan zelf beslissen onder Project → Omgevingen → Hoe wijzigingen worden gevalideerd → Remote validatie voor dit project: Instelling van de werkruimte overnemen, Toegestaan voor dit project of Niet toegestaan voor dit project. De instelling verschijnt alleen bij een strategie met een run in jouw omgeving: Je eigen Kubernetes-omgeving of Eerst Docker, daarna je eigen omgeving.

Ontbreekt een van deze, dan wordt de run geweigerd met het ontbrekende onderdeel benoemd, in plaats van ongemerkt ergens anders te draaien.

Eén bewijs kan je runner niet leveren: dat de applicatie nog start. Voordat een wijziging wordt toegepast, start FixControl normaal de applicatie en wacht tot die antwoordt. Een runner bij de klant kan die controle niet doen; de run legt hem vast als niet ondersteund. Een project waarvan de geverifieerde omgeving een startcommando declareert, kan daarom geen wijzigingen toepassen totdat een van deze twee geldt:

• de strategie is Eerst Docker, daarna je eigen omgeving, zodat de startcontrole eerst op FixControls eigen lane gebeurt; of
• een beheerder of manager heeft Wijzigingen toestaan zonder dit bewijs aangezet onder Bewijs dat de applicatie nog start op dezelfde pagina. Dat is een expliciete acceptatie, vastgelegd met naam en datum naast elke goedkeuring die erop leunt.

Windows, .NET Framework en WinDev

FixControl detecteert .NET Framework-projecten (net48 en verwanten), moderne .NET-projecten die op Windows mikken (een -windows-target-framework, zoals WinForms of WPF), en WinDev-projecten, en plant hun echte build- en testcommando's — NuGet-restore, MSBuild en VSTest voor .NET Framework. Modern .NET dat geen Windows nodig heeft, draait op Linux zoals elke andere stack.

Windows-builds worden vandaag niet geverifieerd. Er is een gehoste Windows-lane voor .NET Framework en -windows-targets gebouwd, maar die staat standaard niet aan en is nog niet bewezen: de image is nooit gebouwd en er heeft nog geen Windows-taak gedraaid. Tot FixControl hem aanzet, stopt zo'n project met een weigering die precies benoemt wat ontbreekt — MSBuild (Visual Studio Build Tools), nuget.exe, vstest.console — en gaat het niet verder.

Eenmaal aan heeft die lane twee grenzen die je nu al moet kennen:

• Hij kan de applicatie niet starten, dus hij kan het startbewijs hierboven niet leveren.
• Hij kan geen sidecar-services draaien. Een Windows-taak kan de Linux-databasecontainers van de andere lanes niet meenemen, dus een .NET Framework-repository die een database declareert, wordt geweigerd met de service benoemd.

WinDev is in elk geval een weigering. Een WinDev-project bouwen vereist een gelicentieerde PC SOFT-installatie, die FixControl niet meelevert, en er is geen WinDev-runner. De weigering benoemt wat ontbreekt.

Dat is de eerlijke uitkomst en de bedoelde. Het alternatief — een net48-solution verifiëren met een Linux-.NET-SDK — zou een groen oordeel opleveren over software die niet de software is die je uitlevert. Een weigering waar je iets mee kunt is meer waard dan een groen dat je niet kunt vertrouwen.

Is Windows-verificatie belangrijk voor je, laat het je FixControl-contact weten.

Kubernetes-permissies (RBAC)

De agent draait onder een minimale Role, en validatie draait onder een apart ServiceAccount:

• Agent — get/list op Argo Rollouts in de namespaces die jij toestaat, plus get/update op precies één benoemde ConfigMap (zijn nonce-grootboek). Standaard heeft hij helemaal geen schrijfrechten op rollouts: het standaard-promotiepad is een GitOps-markercommit die je eigen in-cluster tooling verifieert en toepast. De pod is gehard (non-root, read-only root filesystem, alle capabilities gedropt, digest-gepinde images).
• Validatie-runner — een apart ServiceAccount in een eigen namespace dat kortlevende testnamespaces, deployments, services en jobs aanmaakt, en Argo-resources helemaal niet kan bereiken. Een ValidatingAdmissionPolicy (afgedwongen door de API-server, standaard toegepast door de installer) weigert elke schrijfactie van deze identiteit buiten de eigen fc-test-*-namespaces.

Compromittering van het onderdeel dat testcode draait mag nooit rollout-controle opleveren — daarom zijn het twee identiteiten.

Argo- en CI-connectiviteit

• Argo Rollouts — de agent observeert rollout-status en promoot, na een goedgekeurde poort, via het geconfigureerde pad. De standaard is een GitOps-markercommit die je eigen promotietooling tegen de live rollout verifieert; de agent directe rollout-API-toegang geven is een aparte keuze die standaard uit staat.
• Jenkins / GitLab (privé) — de CI-credential leeft in een secret in jouw cluster, bewust gescheiden van de FixControl-identiteit van de agent, zodat beide onafhankelijk roteren. De operatie-envelop voor CI-verdicts bevat geen doel-URL — de agent praat alleen met het CI-hostadres dat aan jouw kant is geconfigureerd, zodat een gecompromitteerde cloud de agent niet naar een willekeurig intern adres kan sturen.
• Wat een poort per CI-host precies doet staat in DevOps & CI/CD.

Secrets

Secret-waarden voor validatieruns verschijnen nooit in FixControls opslag, operatie-payloads, logs of bewijs — er zijn er geen om te verschijnen. Een koppelmodel per project (een secret bij naam noemen, runner-zijde opgelost) bestaat in het schema, maar geen enkele executor leest het al; reken er dus niet op.

Bewijs en health

• Elk operatieresultaat — succes, falen, weigering, verval — wordt teruggemeld en sluit in één audittrail aan op de goedkeuring die het veroorzaakte.
• Agent-connectiviteit is een volwaardige health-capability: een gemiste heartbeat verschijnt binnen minuten als gedegradeerd, per agent, in plaats van zich te verschuilen achter een generieke "connected"-status.
• Validatieruns rapporteren hetzelfde bewijscontract als FixControls geïsoleerde Docker-validatie: omgevingshash, image-digests, uitgevoerd plan, resultaat. Zie Change-validatie.

Faalgedrag

• FixControl onbereikbaar — je workloads blijven draaien; de agent haalt simpelweg geen nieuwe operaties op. Tijdelijke fouten worden met backoff opnieuw geprobeerd, elke poging opnieuw getekend met een verse tijdstempel; permanente (4xx-)fouten worden niet blind herhaald.
• Agent plat — openstaande operaties verlopen zichtbaar; de goedkeuring op de poort blijft vastgelegd, en de tijdlijn toont dat uitvoering niet plaatsvond. Niets wordt te laat uitgevoerd.
• Weigeringen — een operatie buiten de lokale allowlist, een onbekende capability, een herhaalde nonce of een downgrade-poging wordt geweigerd, en de weigering wordt teruggemeld en als governance-bevinding vastgelegd.
• Gedegradeerde nonce-opslag — kan de agent zijn nonce-grootboek niet schrijven, dan valt hij terug op in-memory-registratie met een luide waarschuwing en een metric; het replay-venster is dan begrensd door de vervaltijd van de operatie (minuten).

Installeren, upgraden, verwijderen

Het pakket ophalen. Bij enrolment staat een downloadlink voor de gepinde release naast de identiteit van de agent, en diezelfde link blijft daarna op de fc-agents-kaart staan — een upgrade, een tweede cluster en een herinstallatie beginnen daar allemaal. Elke release bevat het installatiearchief, de SHA-256-checksum, een image-pins.env met de twee digest-gepinde imageverwijzingen die het values-bestand nodig heeft, CycloneDX-SBOM's en de image-digests.

Verifieer voor je draait. De images zijn ondertekend met een keyless Sigstore-handtekening die aan de release-workflow hangt, dus er is geen sleutel van ons die je hoeft te bewaren of vertrouwen:

cosign verify ghcr.io/fixcontrol-ai/fc-agent@sha256:... \
  --certificate-identity-regexp '^https://github.com/FixControl-AI/fixcontrol-agent/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

cosign verify-attestation --type cyclonedx controleert de SBOM op dezelfde manier — een geattesteerde SBOM hangt aan de digest, een gedownload bestand niet. De exacte commando's staan in de README van het pakket.

De images zelf bouwen kan en de broncode zit in het archief — een air-gapped omgeving, of beleid dat alleen intern gebouwde images toestaat, heeft build-images.sh, een eigen registry en de digests die het script afdrukt nodig; verder verandert er niets.

Wat erin zit. De manifests, een idempotente install.sh gedreven door één values.env, een verify.sh die het resultaat tegen het draaiende cluster controleert, plus rotatie-, intrek- en verwijderscripts.

Upgraden is de nieuwe release downloaden, je values.env meenemen, de nieuwe regels uit image-pins.env plakken en de installer opnieuw draaien. Agent en FixControl onderhandelen bij elke poll over capabilities, dus een nieuwere server en een oudere agent blijven werken binnen wat beide begrijpen; een release die een nieuwere agent vereist, vermeldt dat in de releasenotes.

Verwijderen is het uninstall-script plus de agent intrekken onder Instellingen → DevOps, waarna zijn requests worden geweigerd.

Problemen oplossen

• Agent direct na installatie unhealthy — de health-probe meldt pas ready na de eerste geslaagde poll; controleer de uitgaande bereikbaarheid naar FixControl en de enrolment-waarden.
• Operaties verlopen zonder uitgevoerd te worden — de agent pollt niet (egress geblokkeerd, secret ingetrokken, pod plat) of is ge-enrold tegen een ander cluster-ID dan de operatie adresseert. Beide verschijnen in de connectiviteits-health en de audittrail.
• Een verdict is goedgekeurd maar er bewoog niets — bekijk de operatie op de tijdlijn van de goedkeuring: een verval, een weigering (met reden) of een leveringsretry staat daar vastgelegd in plaats van verloren te gaan.

Zie ook: Verificatie en resultaten · DevOps & CI/CD · Change-validatie · Security & audit.