unYOLO

unYOLO stelt je in staat om gedetailleerde beleidsregels (fine-grained policies) in een lokaal bestand te beheren. Hierdoor zijn er geen toestemmingsschermen waar doorheen geklikt moet worden en hoeft er geen apart account voor de agent aangemaakt te worden. Wanneer de agent meer rechten nodig heeft, kun je tijdelijke machtigingen (timed grants) verlenen die automatisch verlopen.

Installatie

De begeleide installateur kan worden uitgevoerd op macOS of Linux via de volgende opdracht:

$ curl -fsSL https://unyolo.io/install.sh | sh

De Credential Boundary (Geloofwaardigheidsgrens)

Agent-tools ontvangen vaak hetzelfde accountbrede token als een menselijke gebruiker zou gebruiken. Een foutief commando kan daardoor elke repository en operatie bereiken die door dat token wordt gedekt.

Een broker bewaart het provider-token in een ander proces. De agent ontvangt een client-credential waarvan de autoriteit voortvloeit uit het beleid. Hierdoor faalt een niet-geautoriseerde force-push al voordat GitHub deze ziet.

Zonder broker

Je geeft het token aan de agent. Deze voert het gewenste werk uit, maar hetzelfde token heeft ook toegang tot alles in je account. Bijvoorbeeld: je geeft je GitHub-token aan de agent om een specifieke branch te pushen; dit token heeft echter ook toegang tot de default branch, de volledige acme/api repository en zelfs een aparte private repository.

Met unYOLO

De broker beheert het token. De agent vraagt om hetzelfde werk, maar aanvragen die je nooit hebt geautoriseerd worden geweigerd. Je geeft je GitHub-token aan de broker. De agent stuurt verzoeken naar de broker, die deze toetst aan het scope.json bestand. Alleen de toegestane branch push wordt doorgelaten en het resultaat teruggegeven; de overige drie acties worden geweigerd.

Het Verzoekpad (Request Path)

Elke broker gebruikt hetzelfde pad voor verzoeken. Alleen de classificatie en uitvoering zijn afhankelijk van de provider.

1. Client-authenticatie: De aanroeper presenteert een benoemd broker-client secret voordat de broker een verzoek accepteert.
2. Classificatie van het verzoek: De provider-adapter identificeert de client en de operatie, samen met de doelattributen (target attrs).
3. Beleidsevaluatie: De gedeelde engine matcht deze combinatie met het regelsbestand.
4. Actieve grants: Een goedgekeurde grant fungeert als een 'allow'-regel met een vervaltijd en een budget voor het aantal keren dat deze gebruikt mag worden.
5. Verzoek om goedkeuring: Een operatie die goedkeuring vereist, wacht in de inbox van de operator en kan ook verschijnen in Telegram.
6. Uitvoering door provider: De broker voert de operatie uit met het credential van de provider en geeft alleen het resultaat terug.
7. Audit-vermelding: De broker registreert de beslissing en de bijbehorende regel-ID's, zonder geheime gegevens op te slaan.

Beslisvolgorde

Ongeacht de volgorde in het bestand, is de beslisvolgorde altijd vastgesteld als volgt: deny → active grant → allow → request → no_match

Een deny wint van alles, inclusief een goedgekeurde grant. Een verzoek dat aan geen enkele regel voldoet (no_match), wordt geweigerd.

Het Beleidsbestand (Policy File)

Een broker laadt bij opstarten één JSON-regelsbestand als bron voor autorisatie. Dit bestand kan direct worden gelezen en wijzigingen kunnen via een pull request worden beoordeeld. unYOLO leidt geen rechten af uit het netwerkverkeer.

Attributen (attrs) zorgen voor de nodige beperking. Een regel kan bijvoorbeeld pushes toestaan naar refs/heads/agent-a/**, terwijl pushes naar de default branch (refs/heads/main) onbedekt blijven en dus worden geweigerd. Onbekende velden, dubbele regel-ID's, niet-ondersteunde operaties en ongeldige globs zorgen ervoor dat de service niet start.

Voorbeelden van beleidsschema's

Toestaan (allow)

{
  "rules": [
    {
      "id": "agent-a-read-and-branch",
      "effect": "allow",
      "clients": ["agent-a"],
      "operations": [
        "contents.read",
        "git.fetch",
        "git.push.fast_forward"
      ],
      "targets": [
        { "kind": "repo", "owner": "acme", "name": "api" }
      ],
      "attrs": {
        "refs": ["refs/heads/agent-a/**"]
      }
    }
  ]
}

Verzoek om goedkeuring (request)

{
  "rules": [
    {
      "id": "request-force-push-to-main",
      "effect": "request",
      "clients": ["agent-a"],
      "operations": ["git.push.force"],
      "targets": [
        { "kind": "repo", "owner": "acme", "name": "api" }
      ],
      "attrs": {
        "refs": ["refs/heads/main"]
      },
      "grant_policy": {
        "mode": "window",
        "default_minutes": 5,
        "max_minutes": 10,
        "default_max_uses": 1,
        "max_uses": 1
      }
    }
  ]
}

Weigeren (deny)

{
  "rules": [
    {
      "id": "never-delete-refs",
      "effect": "deny",
      "clients": ["*"],
      "operations": ["git.ref.delete"],
      "targets": [{ "kind": "repo" }],
      "description": "Deletion is never delegated, even under an approved grant."
    }
  ]
}

Goedkeuring door de Operator

Het markeren van een operatie als request creëert een duurzaam goedkeuringsrecord en houdt de oorspronkelijke aanroep open. Zodra er goedkeuring is gegeven, wordt bijvoorbeeld een git push hervat als dezelfde push. Een weigering, verlopen termijn of wijziging in de status stroomopwaarts resulteert in een normale Git-foutmelding en stuurt niets door.

Operators beslissen via een beveiligde inbox op een aparte listener met eigen credentials. Telegram kan hetzelfde goedkeuringsrecord weergeven. Beide interfaces sluiten het verzoek precies één keer af, waarbij de goedkeuring enkel de duur of het aantal keren van gebruik kan beperken.

Hoe goedkeuringen technisch werken

Opvragen van openstaande verzoeken:

operator@host $ curl -sS --unix-socket "$OPERATOR_SOCK" \
-H "Authorization: Bearer $OPERATOR_TOKEN" \
localhost/api/operator/v1/requests?status=pending

Resultaat:

{
  "items": [{
    "id": "g_01JQ8W3M",
    "revision": 3,
    "requester": "agent-a",
    "operation": "git.push.force",
    "presentation": {
      "title": "Rewrite history on acme/api",
      "risk": "high",
      "warnings": ["Removes 2 commits from main"]
    }
  }]
}

Goedkeuren van een verzoek (bijv. beperken tot twee minuten):

$ curl -sS -X POST .../g_01JQ8W3M/approve -d '{
  "expected_revision": 3,
  "constraints": {"duration_seconds": 120}
}'

Resultaat: 200 state=active uses_remaining=1

Inbegrepen Brokers

De repository bevat brokers voor GitHub en Hugging Face. Daarnaast is er de sudo-broker voor goedgekeurde Unix-commando's. Elke broker draait als een apart proces en heeft geen toegang tot de credentials van andere providers.

• gh-broker: Beheert GitHub App credentials. Voor verzoeken met een repository-scope genereert deze een kortstondig installatie-token, beperkt tot die specifieke repository en de minimale benodigde rechten (bijv. pullrequest.create, git.push.fastforward, contents.read).
• hf-broker: Beheert een Hugging Face token voor Hub repositories en Router inference. Deze analyseert Git- en LFS-pushes voordat ze worden doorgestuurd, waardoor het herschrijven van historie bij de broker stopt (bijv. git.push.append, repo.contents.read, bucket.object.write).
• sudo-broker: Voert één exact commando uit uit een root-owned catalogus als een andere Unix-gebruiker. Het weigert shell-strings, willekeurige executables, TTY's of door de aanroeper opgegeven omgevingen (bijv. exec.command).

Eigen Brokers Bouwen

De meegeleverde brokers maken gebruik van hetzelfde framework dat beschikbaar is voor aangepaste providers. Om een interne API-sleutel of cloud-rol te beschermen, kun je een provider-specifieke classifier en executor implementeren. Gedeelde pakketten leveren de mechanismen voor beleid en goedkeuring.

Wat je zelf schrijft:

• Een classifier die de client en operatie identificeert met de bijbehorende doelattributen.
• Een registry waarin operaties en hun doeltypen worden gedeclareerd, inclusief geaccepteerde attributen.
• Een executor die het credential beheert en de actie uitvoert.
• Teksten voor goedkeuring, inclusief een titel, risicofactoren en waarschuwingen.

Wat je overneemt (geërfd):

• Client- en operator-authenticatie via aparte credentials.
• De policy engine en de vaste beslisvolgorde.
• De lifecycle van grants met gebruikbudgetten, reserveringen en idempotente retries.
• De operator inbox, SSE cursors en het Telegram-kanaal.
• Agent Operations V1, de MCP bridge en herstel na herstart.
• Secret-safe audits, installers, service rendering en doctor checks.