Forbered en database til CodeQL

  • 5 minutter

CodeQL behandler kode som data. CodeQL-analyse er afhængig af at udtrække relationsdata fra din kode og bruge dem til at oprette en CodeQL-database. Disse databaser indeholder alle de vigtige oplysninger om en kodebase.

Du kan derefter køre CodeQL-forespørgsler mod denne database for at identificere sikkerhedssårbarheder, fejl og andre fejl. Du kan skrive dine egne forespørgsler eller køre Standard CodeQL-forespørgsler, der er skrevet af GitHub-forskere og communitybidragydere.

Du kan bruge den selvstændige CodeQL CLI til at oprette og analysere en CodeQL-database. Analyse af databasen genererer resultater i Static Analysis Results Interchange Format (SARIF), som kan uploades til et GitHub-repository for at se advarselsdetaljer.

CodeQL-scanningsarkitektur

CodeQL-scanning følger en pipeline, der omdanner kildekode til forespørgelige data, udfører sikkerhedsforespørgsler og offentliggør resultaterne som kodescanningsadvarsler.

Scanningsarbejdsgangen er:

  1. Kildekode: CodeQL starter med indholdet af repositoriet ved den commit, der analyseres.
  2. Udvinding: En sprogspecifik udtrækker læser koden og indsamler fakta om kildefiler, syntaks, kontrolflow og dataflow.
  3. Oprettelse af databaser: De udtrukne fakta gemmes i en CodeQL-database. Hver database repræsenterer ét sprog i kodebasen.
  4. Forespørgselsudførelse: CodeQL kører GitHub-vedligeholdte forespørgsler, fællesskabsforespørgsler eller brugerdefinerede forespørgsler mod databasen.
  5. SARIF-generering: Forespørgselsresultater skrives i Static Analysis Results Interchange Format (SARIF).
  6. GitHub-kodescanning: SARIF-resultater uploades til GitHub og vises som kodescanningsadvarsler.

Denne arkitektur adskiller kodeudtrækning fra forespørgselsudførelse. Når en database er oprettet, kan du køre forskellige forespørgselssuiter mod den samme database uden at udtrække koden igen.

Sprogstrategi

CodeQL understøtter både kompilerede og fortolkede sprog, men udtrækningsstrategien afhænger af sprogtypen.

Kompilerede sprog

For kompilerede sprog såsom:

  • C/C++
  • C#
  • Java
  • Kotlin
  • Rust
  • Hurtig
  • Gå

CodeQL skal ofte forstå, hvordan projektet bygges. Under databaseoprettelsen kan CodeQL overvåge build-processen, så den kan udtrække de kildefiler, som compileren har behandlet.

For de mest pålidelige resultater skal du konfigurere eksplicitte build-kommandoer i stedet for at stole på autobuild eller ingen build-muligheder .

Fortolkede sprog

For fortolkede sprog såsom:

  • Pyton
  • JavaScript/TypeScript
  • Ruby

CodeQL udtrækker information direkte fra kildekoden uden at kræve en separat build-kommando.

Flersprogede arkiver

For repositorier, der indeholder flere understøttede sprog:

  • Opret en separat database for hvert sprog.
  • I GitHub Actions skal man bruge en sprogmatrix, så hvert sprog initialiseres, udtrækkes og analyseres korrekt.

Databaseforberedelse til CodeQL

Før generering af en CodeQL-database:

  1. Installer og konfigurér CodeQL CLI.
  2. Tjek den version af kodebasen, du vil analysere.

For kompilerede sprog:

  • Sørg for, at projektet er klar til at blive bygget.
  • Installer alle nødvendige afhængigheder på forhånd.
  • CodeQL udtrækker en relationel repræsentation af hver kildefil for at oprette databasen.

For fortolkede sprog:

  • Extractoren kører direkte på kildekoden.
  • Afhængigheder løses automatisk under udtrækningen.

For kompilerede sprog overvåger CodeQL den normale build-proces. Hver gang compilatoren behandler en kildefil, laver CodeQL en kopi og udtrækker al relevant information, der er nødvendig for analysen.

Konfiguration af kommandolinjegrænseflade

Følg disse trin for at installere CodeQL CLI.

1. Download CodeQL CLI-pakken

Den anbefalede installationsmetode er at downloade den medfølgende pakke, hvilket sikrer kompatibilitet mellem CLI, biblioteker og forespørgselspakker.

Pakken inkluderer:

  • The CodeQL CLI
  • Kompatible CodeQL-forespørgsler og biblioteker
  • Forudkompilerede forespørgselspakker

For at downloade pakken:

  1. Gå til Releases-siden i CodeQL's offentlige repository.
  2. Download det platformspecifikke bundt under Assets.

Udgivelsessiden indeholder også:

  • Udgivelsesbemærkninger
  • Tidligere versioner
  • codeql-bundle.tar.gz, som understøtter alle platforme

2. Udtræk arkivet

Udpak arkivet .zip til en mappe efter eget valg.

Brugere af macOS Catalina (eller senere) skal gennemføre yderligere opsætningstrin som beskrevet i CodeQL CLI-dokumentationen.

3. Kør CodeQL

Efter udtrækning kan enten:

  • Køre:
<extraction-root>/codeql/codeql

eller

  • Tilføje:
<extraction-root>/codeql

til dit system PATH , så du kan påkalde CLI'en simpelthen som:

codeql

Du kan nu køre CodeQL-kommandoer.

Verificér din CLI-opsætning

Kør følgende kommandoer for at bekræfte, at din installation fungerer korrekt.

Vis installerede CodeQL-pakker:

codeql resolve packs

Hvis eksekverbaren fil ikke er i din PATH, brug:

<extraction-root>/codeql/codeql resolve packs

Hvis forventede sprogpakker mangler, så tjek at du har downloadet CodeQL-pakken, ikke den selvstændige CLI.

Vis understøttede sprog:

codeql resolve languages

Databaseoprettelse

Opret en CodeQL-database fra roden af dit projekt:

codeql database create <database> --language=<language-identifier>

Erstatte:

  • <database> med destinationskataloget.
  • <language-identifier> med sprogidentifikatoren til analyse.

Du kan også bruge følgende indstillinger:

Mulighed Formål
--source-root Angiver rodmappen, der indeholder kildekoden.
--db-cluster Opretter databaser for flere sprog.
--command Specificerer build-kommandoen for kompilerede sprog. Ikke påkrævet for Python, Ruby eller JavaScript.
--no-run-unnecessary-builds Springer unødvendige builds over, når den bruges med --db-cluster.

Efter vellykket udførelse:

  • En ny databasemappe oprettes.
  • Når man bruger --db-cluster, oprettes en undermappe for hvert sprog.

Hver database indeholder:

  • Relationelle analysedata
  • Kildearkiv
  • Metadata nødvendig for CodeQL-analyse

Kildearkivet er et øjebliksbillede af kildefilerne på det tidspunkt, hvor databasen blev oprettet, og bruges til visning af analyseresultater.

Databasegenerering og ydeevneovervejelser

Efter at have oprettet en CodeQL-database, er det vigtigt at forstå, hvordan databasegenerering fungerer, og hvordan det påvirker ydeevnen.

Databasegenereringsmetoder

Du kan generere CodeQL-databaser ved hjælp af enten:

CodeQL-kommandolinjegrænseflade

Opret databaser og kør analyser manuelt.

Denne tilgang er nyttig til:

  • Lokal udvikling
  • Fejlfinding
  • Avancerede konfigurationer

Arbejdsprocesser for GitHub-handlinger

De fleste organisationer automatiserer databasegenerering via GitHub Actions.

En typisk arbejdsgang:

  1. Initialiserer CodeQL.
  2. Opretter databaser.
  3. Kører forespørgsler.
  4. Uploader SARIF-resultater til GitHub.

Databaser pr. sprog

CodeQL opretter en separat database for hvert understøttet sprog.

Hvert sprog:

  • Bruger sin egen ekstraktor.
  • Bruger sit eget databaseskema.
  • Analyseres uafhængigt.

For flersprogede repositorier, enten:

  • Brug muligheden --db-cluster med CLI.
  • Konfigurér en sprogmatrix i GitHub Actions.

En sprogmatrix muliggør parallel analyse og komplet sprogdækning.

Build-baseret udvinding for kompilerede sprog

For kompilerede sprog:

  • CodeQL overvåger byggeprocessen.
  • Buildet skal gennemføres med succes.
  • Automatisk autobuilding fungerer ikke pålideligt for alle projekter.

For de bedste resultater defineres eksplicitte bygge-trin før analysen.

For fortolkede sprog udtrækker CodeQL direkte fra kildekoden uden at kræve en build.

Ydelsesovervejelser

Tid til oprettelse og analyse af databaser afhænger af flere faktorer.

Repository-størrelse

Større arkiver kræver mere tid til udtrækning og analyse.

Flere sprog

Brug en sprogmatrix til at analysere sprog parallelt og reducere den samlede køretid.

CI-ressourcer

CodeQL-analyse kan være ressourcekrævende.

At øge CPU eller hukommelse for runners kan forbedre ydeevnen markant.

Analyseområde

Du kan reducere analysetiden ved at begrænse den kode, der scannes, for eksempel ved at udelukke:

  • Test filer
  • Genereret kode

Generelt er analysetiden proportional med mængden af kildekode, der behandles.

Oprettelse og fornyelse af databasen

En CodeQL-database repræsenterer et øjebliksbillede af kodebasen på et bestemt tidspunkt.

  • En ny database oprettes for hver analyse, der køres.
  • Databaser opdateres ikke gradvist.
  • Enhver ændring i kodebasen kræver en ny database.

Du gengenererer typisk databaser, når:

  • Nye commits bliver presset.
  • Pull requests åbnes eller opdateres.
  • Ændringer i build-konfigurationen.
  • Ændringer i forespørgselssæt eller analysekonfiguration.

Da databasegenerering er en del af hver scanning, er det vigtigt at tilpasse scanninger til meningsfulde begivenheder, såsom pull requests eller planlagte kørsler.

Udsugningsanlæg

En udtrækning er et værktøj, der producerer relationsdata og kildereference for hver inputfil, hvorfra der kan oprettes en CodeQL-database. Hvert sprog, som CodeQL understøtter, har én udtrækning. Denne struktur sikrer, at udtrækningsprocessen er så nøjagtig som muligt.

Hver udtrækning definerer sit eget sæt konfigurationsindstillinger. Hvis du angiver codeql resolve extractor --format=betterjson, resulterer det i data, der er formateret som i følgende eksempel:

{
  "extractor_root": "/home/user/codeql/java",
  "extractor_options": {
    "option1": {
      "title": "Java extractor option 1",
      "description": "An example string option for the Java extractor.",
      "type": "string",
      "pattern": "[a-z]+"
    },
    "group1": {
      "title": "Java extractor group 1",
      "description": "An example option group for the Java extractor.",
      "type": "object",
      "properties": {
        "option2": {
          "title": "Java extractor option 2",
          "description": "An example array option for the Java extractor",
          "type": "array",
          "pattern": "[1-9][0-9]*"
        }
      }
    }
  }
}

For at finde ud af, hvilke muligheder der er tilgængelige for dit sprogs extractor, indtast:

  • codeql resolve languages --format=betterjson, eller
  • codeql resolve extractor --format=betterjson.

Outputformatet betterjson indeholder også udtrækningens rod og andre sprogspecifikke indstillinger.

Data i en CodeQL-database

En CodeQL-database er en enkelt mappe, der indeholder alle de data, der kræves til analyse. Disse data omfatter relationsdata, kopierede kildefiler og et sprogspecifikt databaseskema, der angiver de indbyrdes relationer i dataene. CodeQL importerer disse data efter udtrækning.

CodeQL-databaser giver et snapshot af et bestemt sprogs data, der kan forespørges på, og som blev udtrukket fra en kodebase. Disse data er en komplet, hierarkisk repræsentation af koden. Det omfatter:

  • En repræsentation af det abstrakte syntakstræ (AST).
  • Dataflow-grafen.
  • Kontrolflow-grafen.

Databaser genereres ét sprog ad gangen for kodebaser med flere sprog. Hvert sprog har sit eget entydige databaseskema. Skemaet indeholder en grænseflade mellem den indledende leksikalske analyse under udtrækningsprocessen og den komplekse analyse via CodeQL.

En CodeQL-database indeholder to hovedtabeller:

  • Udtrykstabellen indeholder en række for hvert udtryk i kildekoden, som CodeQL analyserede under byggeprocessen.
  • Sætningstabellen indeholder en række for hver sætning i kildekoden, som CodeQL analyserede under byggeprocessen.

CodeQL-biblioteket definerer klasser for at give et lag af abstraktion over hver af disse tabeller. Dette lag indeholder de relaterede hjælpetabeller Expr og Stmt.

Potentielle CodeQL-mangler

Databaseoprettelse i kodescanningsarbejdsgangen har nogle potentielle mangler. Dette afsnit omhandler specifikt brugen af GitHub CodeQL Action.

Du skal bruge en sprogmatrix til autobuild for at bygge hvert af de kompilerede sprog, der er listet i matricen. Du kan bruge en matrix til at oprette job til mere end én understøttet version af et programmeringssprog, et operativsystem eller et værktøj.

Hvis du ikke bruger en matrix, prøver autobuild at bygge det understøttede kompilerede sprog med flest kildefiler i repositoryet. Analysen af kompilerede sprog, bortset fra Go, mislykkes ofte, medmindre du angiver eksplicitte kommandoer til at oprette koden, før du udfører analysetrinnet.

Adfærden af autobuild-trinnet varierer afhængigt af det operativsystem, som sprogudtrækkeren kører på. Autobuild-trinnet forsøger automatisk at opdage en passende build-metode for sproget baseret på operativsystemet. Denne adfærd kan føre til upålidelige resultater for kompilerede sprog og kan ofte resultere i en mislykket kørsel.

Vi anbefaler, at du konfigurerer et build-trin i kodescannings-workflowfilen, som kører før analysen, i stedet for at lade autobuild forsøge at bygge kompilerede sprog. På denne måde er arbejdsprocesfilen skræddersyet til systemets og projektets buildkrav til mere pålidelige scanninger.

Du kan læse mere om specifikke sprog og autobuild-trinene i CodeQL autobuild-dokumentationen.

VS Code-udvidelse

Du kan bruge Visual Studio Code (VS Code) og CodeQL-udvidelsen til at kompilere og køre forespørgsler, så længe du bruger VS Code 1.39 eller nyere. Du kan downloade udvidelsen fra Visual Studio Code Marketplace eller ved at downloade CodeQL VSIX-filen.

Udvidelsen bruger den installerede kommandolinjegrænseflade, der blev fundet i PATH, hvis den er tilgængelig. Hvis ikke, administrerer udvidelsen automatisk adgang til den eksekverbare fil for kommandolinjegrænsefladen for dig. Automatisk administration sikrer, at kommandolinjegrænsefladen er kompatibel med CodeQL-udvidelsen.