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 kjøringsmiljøets sandkasse kjører Archgate en statisk analysesikkerhetsskanner på hver .rules.ts-fil før den kjøres. Skanneren parser regelens AST og blokkerer filer som inneholder farlige mønstre:

| Mønster | Blokkert | | ------------------------------------------------------------------- | -------- | | Import av node:fs, child_process, net, http, vm, osv. | Ja | | Bun.spawn(), Bun.write(), Bun.file(), Bun.$ | Ja | | fetch() | Ja | | eval(), new Function() | Ja | | Beregnet egenskapstilgang (Bun[variable], globalThis[variable]) | Ja | | Dynamisk import() med ikke-literal argument | Ja | | Tilordning til globalThis eller process.env | Ja |

Hvis et forbudt mønster finnes, blir regelfilen ikke importert eller kjørt, og archgate check avslutter med en feil.

Trygge moduler som er tillatt: node:path, node:url, node:util, node:crypto — dette er verktøymoduler uten filsystem-, nettverks- eller prosess-I/O-funksjonalitet.

Skanneren hever terskelen fra “trivielt å utnytte” til “krever bevisst obfuskering som ser mistenkelig ut i kodegjennomgang.” Veloppførte regler bruker bare RuleContext-metodene (ctx.readFile, ctx.grep, ctx.glob, osv.) og ctx.report for utskrift.

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.
• Bruke farlige API-er — sikkerhetsskanneren blokkerer import av systemmoduler (fs, child_process, net, osv.), Bun-API-er (Bun.spawn, Bun.file), nettverkstilgang (fetch) og kodegenerering (eval, new Function). Regelfiler som inneholder disse mønstrene avvises før kjøring.

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, blokkerer sikkerhetsskanneren automatisk farlige mønstre i .rules.ts-filer. Du bør likevel gjennomgå regelfiler før du kjører archgate check for første gang:

• Skanneren fanger eksplisitt bruk av forbudte API-er, men sofistikert obfuskering (f.eks. Reflect.get(Bun, "spawn")) kan omgå den
• 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, 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.