Joachim Friberg
131 lines
4.9 KiB
Markdown
131 lines
4.9 KiB
Markdown
# AGENTS.md
|
|
|
|
Detta dokument styr hur agenter och utvecklare arbetar i detta repo.
|
|
Fokus: korrekthet, låg risk och underhållbarhet.
|
|
|
|
## 1) Syfte och prioritet
|
|
|
|
- Gäller hela repot.
|
|
- Kompletterar globala agentinstruktioner.
|
|
- Vid konflikt gäller striktare regel.
|
|
|
|
## 2) Repo-invarianter
|
|
|
|
- Appfiler ligger under `Apps/<app-id>/`.
|
|
- Varje app ska minst ha:
|
|
- `docker-compose.yaml`
|
|
- `README.md` (syfte, portar, volymer, privilegier, risker)
|
|
- Compose ska ha giltig top-level `name` (gemener + bindestreck).
|
|
- Om `container_name` används måste den vara max 32 tecken och bara innehålla `0-9`, `a-z`, `A-Z`, `_`, `-`.
|
|
- Endast `.yaml` används i repot (aldrig `.yml`).
|
|
- Swap-filer (t.ex. `*.swp`, `*.swo`) ska alltid ignoreras och får aldrig committas.
|
|
|
|
## 3) Säkerhetsbaseline (Compose)
|
|
|
|
MUST:
|
|
- Pinna images till explicit version eller digest.
|
|
- Inte använda `:latest`.
|
|
- Hålla volymer snäva (`/DATA/AppData/$AppID/...`).
|
|
- Vid förslag/byte av `image:` måste imagen verifieras online (manifest/tag finns i registry) innan merge.
|
|
- Använd App/_template som grund om inget annat anges.
|
|
- deply.resources.reservations ska sättas till något passande. Detta kommer även parsas av ZimaOS webui
|
|
|
|
SHOULD:
|
|
- `security_opt: ["no-new-privileges:true"]`
|
|
- `cap_drop: ["ALL"]` när appen tillåter det.
|
|
|
|
Högrisk-inställningar är tillåtna men kräver varning och motivering:
|
|
- `privileged: true`
|
|
- `network_mode: host`
|
|
- mount av Docker-socket (`/var/run/docker.sock`)
|
|
|
|
Om någon högrisk-inställning används måste appens `README.md` innehålla:
|
|
- varför det behövs,
|
|
- vilka alternativ som utvärderats,
|
|
- vilka risker det innebär.
|
|
|
|
## 4) Arbetsflöde för ändringar
|
|
|
|
- Små, reviewbara ändringar först.
|
|
- Beskriv säkerhetspåverkan i PR.
|
|
- Lokal validering är rekommenderad under utveckling:
|
|
|
|
```bash
|
|
./scripts/validate-appstore.sh
|
|
```
|
|
|
|
- Lokal validering är inte blockerande för varje enskild commit.
|
|
|
|
## 5) Obligatorisk release-checklista
|
|
|
|
Inför release/publicering måste följande vara uppfyllt:
|
|
|
|
1. `./scripts/validate-appstore.sh` körd med `Validation OK`.
|
|
2. Ingen app använder `image: ...:latest`.
|
|
3. `x-casaos` metadata är satt och konsekvent.
|
|
4. Appens `README.md` är uppdaterad.
|
|
5. Eventuella högrisk-inställningar är tydligt motiverade.
|
|
|
|
## 6) Review-krav
|
|
|
|
PR som ändrar appar ska explicit ange:
|
|
- vilka app-id:n som påverkas,
|
|
- säkerhetsrisk (låg/medel/hög),
|
|
- om högrisk-inställningar introduceras eller ändras.
|
|
|
|
## 7) Testkrav för containerappar
|
|
|
|
För nya appar eller större ändringar i befintliga appar (routing, discovery, auth, nätverk, secrets, cert-hantering) ska integrationstester ingå.
|
|
|
|
Minimikrav:
|
|
|
|
- Testa med mockade externa gränser (t.ex. Docker API, reverse proxy API, DNS/API-provider), så testerna är reproducerbara lokalt.
|
|
- Verifiera minst ett fail-closed-scenario (saknad/ogiltig secret, API-fel, otillåten metadata) där appen inte exponerar tjänster oavsiktligt.
|
|
- Verifiera att endast explicit tillåtna containrar/endpoints exponeras.
|
|
|
|
Tester ska dokumenteras i appens `README.md` med exakt körkommando.
|
|
|
|
## 8) Branch-namnstandard
|
|
|
|
När en ny branch skapas ska formatet vara:
|
|
|
|
`<appnamn>/<initial|bugfix|update>/<detalj>`
|
|
|
|
Regler för `<detalj>`:
|
|
|
|
- `initial`: max 5 ord som beskriver vad som byggs.
|
|
- `bugfix`: vad som fixas (kort och konkret).
|
|
- `update`: versionsuppdatering i formen `vX.Y.Z-to-vA.B.C`.
|
|
|
|
## 9) Parallellt agentarbete och git-scope
|
|
|
|
- När en ny app skapas ska en ny mapp alltid skapas under `Apps/<app-id>/`.
|
|
- Flera agenter kan arbeta samtidigt. Fråga alltid innan du skapar ny branch eller byter branch, för att undvika krockar.
|
|
- `git add` och `git commit` får endast omfatta filer i den egna appens undermapp under `Apps/<app-id>/`.
|
|
- För varje fil som en agent tänker ändra ska agenten först skapa en tom låsfil: `<filnamn>.agent_wip`.
|
|
- Om `<filnamn>.agent_wip` redan finns ska agenten vänta 60 sekunder och kontrollera igen.
|
|
- Upprepa väntan i upp till 10 minuter (10 försök). Om låsfilen fortfarande finns efter 10 minuter: avbryt och be användaren om beslut.
|
|
- När agenten är klar med filen ska motsvarande `<filnamn>.agent_wip` tas bort direkt.
|
|
- Låsfilen ska tas bort även vid fel/avbrott så långt det går, för att undvika falska lås.
|
|
|
|
## 10) Verifieringsdokument när app är redo
|
|
|
|
När en app bedöms som \"redo\" ska appmappen innehålla en verifieringsfil:
|
|
|
|
- `Apps/<app-id>/HOW_TO_VERIFY.md`
|
|
|
|
Filen ska vara praktiskt körbar och innehålla:
|
|
|
|
- tydliga förutsättningar (miljö, DNS, secrets, beroenden),
|
|
- positiva testfall med förväntade resultat,
|
|
- minst ett fail-closed/negativt testfall,
|
|
- exakta kommandon för att verifiera DNS, nät och TLS,
|
|
- en sektion \"data att samla\" för snabb Codex-felsökning.
|
|
|
|
Sektionen \"data att samla\" ska minst täcka:
|
|
|
|
- versions-/buildinfo (appversion, branch/commit eller zip + checksum),
|
|
- relevant konfiguration (med maskade secrets),
|
|
- loggar från berörda containers,
|
|
- konkreta felobservationer (hostname, tidpunkt, förväntat vs faktiskt beteende).
|