Sikkerhet

Archgate kjører TypeScript-regler fra .rules.ts-filer i repositoriet ditt. Denne siden forklarer tillitsmodellen, hva regler kan og ikke kan gjøre, og hvordan du kjører sjekker trygt.

Tillitsmodell

.rules.ts-filer er kjørbar kode. Når du kjører archgate check, importerer CLI-en dynamisk hver .rules.ts-følgestykke-fil og kjører check-funksjonene. Dette tilsvarer å kjøre bun .archgate/adrs/*.rules.ts — koden har de samme mulighetene som ethvert annet skript på maskinen din.

Dette betyr:

• Kjør bare archgate check på repositorier du stoler på.
• Gjennomgå .rules.ts-filer med samme grundighet som all annen kildekode i prosjektet.
• I open source-prosjekter, behandle .rules.ts-endringer i pull requests som sikkerhetssensitive.

Hva regler kan få tilgang til

Regler mottar et RuleContext-objekt med sandkassede filoperasjoner. Alle RuleContext-metoder (readFile, readJSON, grep, grepFiles, glob) er begrenset til prosjektets rotkatalog — stitraversering via ../, absolutte stier og symbolske lenker er blokkert og kaster en feil.

I tillegg til RuleContext-begrensningene på filstier over kjører Archgate en statisk analysesikkerhetsskanner på hver .rules.ts-fil før den kjøres. Ingen av dem er en kjøretidssandkasse — en regel kjører fortsatt i samme prosess med dine rettigheter; skanneren er en statisk port, og begrensningene gjelder bare RuleContext-API-et som en veloppført regel bruker. Fordi en regelfil kjører i samme prosess med fulle rettigheter til den som kjører archgate check, er enhver modul den kan nå vilkårlig kode — derfor bruker skanneren en tillatelsesliste, ikke en forbudsliste: en regel kan bare importere et lite sett med trygge moduler, og alt annet avvises.

De eneste modulene en regelfil kan importere er node:path, node:url, node:util og node:crypto — verktøymoduler uten filsystem-, nettverks- eller prosessfunksjonalitet. De må bruke node:-prefikset; de nakne formene (path) kan overskygges av en pakke i målprosjektet og er blokkert. Enhver annen import avvises, uansett form — statisk (import ... from), dynamisk (await import(...), enten spesifikatoren er en literal eller en variabel), re-eksportert (export ... from), eller nådd gjennom require() / import.meta.require().

Skanneren blokkerer også de andre måtene å nå kode eller funksjonalitet utenfor dette settet:

Mønster	Blokkert
Import av enhver annen modul enn de fire tillatte ovenfor	Ja
require(), import.meta.require()	Ja
Bun.spawn(), Bun.spawnSync(), Bun.write(), Bun.file(), Bun.$	Ja
fetch()	Ja
eval(), new Function()	Ja
process.binding(), process.dlopen() (på ethvert alias av process)	Ja
Beregnet egenskapstilgang (Bun[variable], globalThis[variable])	Ja
Tilordning til globalThis eller process.env	Ja
Bidireksjonale eller usynlige Unicode-tegn (“Trojan Source”)	Ja

Hvis noe av dette finnes, blir regelfilen ikke importert eller kjørt, og archgate check avslutter med en feil.

Fordi skanneren jobber ut fra det parsede syntakstreet, ser den gjennom escape-sekvenser: await import("\x6e...") løses til det samme modulnavnet som tillatelseslisten sjekker, så strengtriks slipper ikke forbi. Det ene en syntakstre ikke kan se, er et tegn som gjør at den viste kildekoden avviker fra koden som faktisk kjøres — derfor avviser skanneren også bidireksjonale og usynlige Unicode-tegn direkte.

Importerte regler skannes også. Når du henter inn tredjeparts regler med archgate adr import, skannes hver .rules.ts — med en strengere sjekk enn førsteparts regler — før den skrives til disk, slik at en importert pakke ikke kan smugle inn kode som din neste archgate check ville kjørt.

Veloppførte regler bruker bare RuleContext-metodene (ctx.readFile, ctx.grep, ctx.glob, ctx.ast, osv.) og ctx.report for utskrift. Når en regel trenger språkverktøy — parsing av Python, eller sammenligning av en fil mot dens grunnleggende git-revisjon — er ctx.ast() den godkjente døren; en regel trenger aldri, og kan ikke åpne, en egen underprosess.

Hva regler ikke kan gjøre

• Skrive filer — RuleContext-API-et er skrivebeskyttet. Regler rapporterer brudd, men kan ikke endre kodebasen.
• Unnslippe 30-sekunders tidsgrensen — hver regel termineres etter 30 sekunder veggtid.
• Påvirke andre regler — regler fra forskjellige ADR-er kjører parallelt, men deler ingen mutbar tilstand gjennom kontekst-API-et.
• Nå utenfor tillatelseslisten via en gjenkjent rute — en regel kan bare importere node:path, node:url, node:util og node:crypto. Import av enhver annen modul, Bun-API-er (Bun.spawn, Bun.file), nettverkstilgang (fetch), underprosess- eller nativ kodetilgang (require, process.binding) og kodegenerering (eval, new Function) avvises før kjøring i sine direkte, gjenkjente former. Dette er en statisk skanning, ikke et fengsel: en evne som settes sammen ved kjøretid er en gjenværende risiko den ikke kan fange, og derfor bør regelfiler du ikke stoler på fortsatt gjennomgås (se nedenfor).

Beste praksis for CI/CD

Å kjøre archgate check i CI er trygt når du kontrollerer repositoriets innhold. Ekstra forsiktighet er nødvendig for pull requests fra eksterne bidragsytere.

Pålitelige grener

For pushes til main eller andre beskyttede grener kjører archgate check kode som allerede er gjennomgått og merget. Dette er trygt:

on:
  push:
    branches: [main]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: archgate/check-action@v1

Pull requests fra forks

Når en pull request kommer fra en fork, kan .rules.ts-filene i PR-en inneholde vilkårlig kode. Dette er den samme risikoen som å kjøre et hvilket som helst ikke-pålitelig CI-skript.

Alternativ 1: Krev godkjenning for kjøring. Bruk GitHubs miljøbeskyttelsesregler eller pull_request_target med manuell godkjenning for å gate CI på gjennomgang:

on:
  pull_request_target:

jobs:
  check:
    runs-on: ubuntu-latest
    environment: pr-check # Krever manuell godkjenning
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.pull_request.head.sha }}
      - uses: archgate/check-action@v1

Alternativ 2: Kjør bare sjekker på pålitelige filer. Bruk en separat arbeidsflyt som sjekker ut basisgrenens .rules.ts-filer og kjører dem mot PR-ens kildefiler. Dette sikrer at bare gjennomgåtte regler kjøres.

Alternativ 3: Hopp over sjekker på fork-PR-er. Hvis reglene dine hovedsakelig er for intern styring, hopp over automatiserte sjekker på fork-PR-er og kjør dem manuelt etter gjennomgang:

on:
  pull_request:

jobs:
  check:
    if: github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: archgate/check-action@v1

Minst-privilegium-kjørere

Kjør archgate check på kjørere med minimale tilganger. Jobben trenger bare lesetilgang til repositoriet — ingen hemmeligheter, distribusjonsnøkler eller skrivetilganger er nødvendig:

jobs:
  check:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: archgate/check-action@v1

Lokal utvikling

Gjennomgå regler i nye repositorier

Når du kloner eller forker et repositorium som bruker Archgate, håndhever sikkerhetsskanneren automatisk importens tillatelsesliste i .rules.ts-filer. Det er en sterk første forsvarslinje — ikke en fullstendig sandkasse — så du bør likevel gjennomgå regelfiler før du kjører archgate check for første gang:

• Skanneren blokkerer de direkte rutene til farlige funksjoner, men den er statisk analyse, ikke et fengsel: alt som bygges ved kjøretid — et egenskapsnavn (obj[name] med et beregnet name) eller en kodestreng — er ugjennomsiktig for en kildeskanning, så gjennomgå regelfiler du ikke stoler på før du kjører dem
• Toppnivå-kode som kjører ved import (før check-funksjonen kalles) kjøres fortsatt hvis den består skanneren
• Veloppførte regler bruker bare RuleContext-metodene (ctx.readFile, ctx.grep, ctx.glob, ctx.ast, osv.) og ctx.report for utskrift

Legitimasjon

Kommandoen archgate login lagrer autentiseringstokenet ditt i operativsystemets legitimasjonsbehandler (macOS Keychain, Windows Credential Manager eller Linux libsecret) via git credential approve. Ingen legitimasjon skrives til disk som klartekstfiler. Tokenet brukes for plugin-installasjon og sendes aldri til tredjeparter utover Archgate plugins-tjenesten.

• Del ikke tokenet i CI-logger. Plugin-installasjonskommandoer sender legitimasjon via autentiserte URL-er til git, som kan dukke opp i prosesslister. Unngå å kjøre archgate plugin install med detaljert logging i delte CI-miljøer.
• For å tilbakekalle tilgang, kjør archgate login logout.

Selvoppdateringsintegritet

Når du kjører archgate upgrade, laster CLI-en ned utgivelsesbinæren fra GitHub Releases og verifiserer SHA256-sjekksummen før den pakkes ut. Hvis sjekksummen ikke stemmer, avbrytes oppgraderingen. Dette beskytter mot manipulerte nedlastinger på grunn av nettverksavlytting eller kompromitterte speil.

Rapportere sårbarheter

Hvis du oppdager et sikkerhetsproblem i Archgate, vennligst rapporter det ansvarlig ved å åpne en GitHub-sak eller kontakte vedlikeholderne direkte. Ikke inkluder utnyttelseskode i offentlige saker.