Aangepaste query's gebruiken met CodeQL

Als u geen aangepast configuratiebestand hebt opgegeven in uw pijplijninstallatie, voert CodeQL het security-extended querypakket uit om uw code te analyseren. U kunt aangepaste CodeQL-query's gebruiken om uw eigen query's te schrijven om specifieke beveiligingsproblemen en fouten te vinden. U moet ook een aangepast configuratiebestand maken om de standaardanalyse van CodeQL te wijzigen.

Als u bestaande aangepaste query's wilt zoeken of uw eigen aangepaste query wilt bijdragen, raadpleegt u Bijdragen aan CodeQL.

Analyse met aangepaste query's

De snelste manier om te beginnen met een aangepaste query is door een query te schrijven en op te slaan in uw lokale Azure DevOps-opslagplaats. U kunt de details van een aangepaste query aanpassen aan uw behoeften, maar deze moet ten minste een regel-id hebben. Zie CodeQL-query's schrijven voor meer informatie over het schrijven van uw eigen CodeQL-query. U kunt ook meerdere query's bundelen in een querysuite of pakketten gebruiken die zijn gepubliceerd door andere personen. Zie Publiceren en gebruiken van CodeQL-pakketten voor meer informatie.

Een aangepast configuratiebestand gebruiken

Een aangepast configuratiebestand is een manier om te beheren welke query's worden uitgevoerd tijdens de analyse van CodeQL op basis van uw code. U kunt meer query's of querypakketten opgeven die moeten worden uitgevoerd en de standaardCodeQL-query's wijzigen of uitschakelen.

Als u een specifieke query wilt opnemen die u wilt opnemen, geeft u de query op met een naam en pad naar de locatie van het querybestand (.ql) in uw opslagplaats.

Als u een specifiek pakket wilt opnemen dat u wilt opnemen, geeft u de naam van het pakket op. U kunt een willekeurig aantal CodeQL-querypakketten opgeven dat moet worden uitgevoerd in uw configuratiebestand.

De volgende stap bestaat uit het maken van een qlpack.yml bestand. Dit bestand declareert het CodeQL-pakket en informatie hierover. Bestanden *.ql in dezelfde map (of submap) als een qlpack.yml onderdeel van het pakket worden beschouwd.

Tip

Het packs-filter van het configuratiebestand biedt ondersteuning voor het downloaden van pakketten uit opslagplaatsen die worden gehost in GitHub, hoewel het queries-filter dat niet doet. Als het pakket privé is in GitHub, moet u een GitHub-toegangstoken opgeven via de AdvancedSecurity-Codeql-Init@1 taak als een omgevingsvariabele en variabelenaam als GITHUB_TOKEN, met het bereik van het token .read:packages

Hier volgt een voorbeeld van een configuratiebestand:

name: "Run custom queries"

# When using a configuration file, if you do not disable default queries,
# then the default CodeQL queries in the `code-scanning` query suite will also execute upon analysis.
disable-default-queries: true
 
# To reference local queries saved to your repository,
# the path must start with `./` followed by the path to the custom query or queries.
# Names for each query referenced is optional.
queries:
  - name: Use security-extended query suite
    uses: security-extended
  - name: Use local custom query (single query)
    uses: ./customQueries/javascript/FindTestFunctions.ql
  - name: Use local custom query (directory of queries)
    uses: ./customQueries/javascript/MemoryLeakQueries  
 
packs:
 - mygithuborg/mypackname
 
paths:
 - src
 
paths-ignore:
  - src/node_modules
  - '**/*.test.js'
 
query-filters:
 - include:
    kind: problem
 - include:
     precision: medium
 - exclude:
    id:
      - js/angular/disabling-sce
      - js/angular/insecure-url-allowlist

Tip

Configuratiebestandspecificaties negeren en hebben voorrang op configuraties op pijplijnniveau voor de AdvancedSecurity-Codeql-Init@1 taak. includepaths / ignorepathswordt genegeerd of, indien paths/paths-ignore aanwezig, overschreven met waarden van .paths/paths-ignore querysuite wordt overschreven met waarden die zijn opgegeven in queries of packs in het configuratiebestand.

Als u een aangepaste query gebruikt, ziet u hier een voorbeeld qlpack.yml in de map met uw aangepaste query's:

version: 1.0.1
dependencies:
  codeql/javascript-all: "*"
  codeql/javascript-queries: "*"

De dependencies variabele bevat alle afhankelijkheden van dit pakket en hun compatibele versiebereiken. Naar elke afhankelijkheid wordt verwezen als het scope/name codeQL-bibliotheekpakket. Bij het definiëren dependenciesis uw qlpack.yml afhankelijk van precies een van de kerntaalpakketten (bijvoorbeeld JavaScript, C#, Ruby, enzovoort), die bepaalt welke taal uw query kan analyseren.

Zie CodeQL-pakketstructuur aanpassen voor meer qlpack.yml specifieke advies- en configuratieopties voor uw configuratiebestand.

Zodra u uw configuratiebestand hebt, moet u de pijplijn waarop CodeQL-analyse wordt uitgevoerd aanpassen om uw nieuwe bestand te kunnen gebruiken. Hier volgt een voorbeeldpijplijn die verwijst naar een configuratiebestand:

trigger: none
 
pool:
  vmImage: windows-latest

# You can either specify your CodeQL variables in a variable block... 
variables:
# `configfilepath` must be an absolute file path relative to the repository root
  advancedsecurity.codeql.configfilepath: '$(build.sourcesDirectory)/.pipelines/steps/configfile.yml' 

# Or you can specify variables as variables for the task. You do not need both definitions. 
steps:
- task: AdvancedSecurity-Codeql-Init@1
  displayName: Initialize CodeQL
  inputs:
    languages: 'javascript'
    loglevel: '2'
    configfilepath: '$(build.sourcesDirectory)/.pipelines/steps/configfile.yml'
# If downloading a pack from GitHub,
# you must include a GitHub access token with the scope of `read:packages`.
  env:
    GITHUB_TOKEN: $(githubtoken)

- task: AdvancedSecurity-Codeql-Analyze@1
  displayName: Perform CodeQL Analysis