codeql agent docker

Agent CodeQL pour Docker

L'agent CodeQL est un projet visant à automatiser l'utilisation de CodeQL. Le projet aide à créer une base de données et à exécuter l'analyse CodeQL. L'agent CodeQL est une image Docker.

L'agent CodeQL pour Docker est également l'image de base de l'agent CodeQL pour le code Visual Studio - une extension pour le code Visual Studio qui simplifie l'utilisation de codeql et exécute automatiquement la numérisation du code.

L'image de l'agent CodeQL est publiée sur Docker Hub sous le nom doublevkay/codeql-agent . Vous pouvez l'utiliser sans construire localement.

Contenu:

• À quoi sert-il?
• Commencer
• Exemples d'utilisation
• Options prises en charge
• Construire
• Comment ça marche?
• Soutien
• Contributif
• Contributeurs
• Notes de libération
• Licence

À quoi sert-il?

L'agent CodeQL pour Docker fournit ces fonctionnalités clés:

• Détection automatique du langage.
• Création de la base de données CodeQL.
• Exécution de l'analyse de la base de données CodeQL.
• Synchronisation automatique la dernière version de CodeQL CLI et de la bibliothèque CodeQL.

Commencer

Bind monte la source, le dossier de résultats et exécuter l'image codeql-agent avec la commande docker suivante.

 docker run --rm --name codeql-agent-docker 
  -v "$PWD:/opt/src" 
  -v "$PWD/codeql-agent-results:/opt/results" 
  doublevkay/codeql-agent

Vous pouvez également spécifier plus d'options pour exécuter l'agent CodeQL. Voir les options prises en charge pour plus de détails.

Options prises en charge

Vous pouvez définir des variables d'environnement pour utiliser les options prises en charge suivantes:

Variable	Description
LANGUAGE	Valeur <language> . Définissez le langage du projet pour créer une base de données ou exécuter Sast. Le <language> doit être: go , java , cpp , csharp , python , javascript , ruby .
USERID	Valeur <id> . Définissez le propriétaire du dossier Résultats sur <id> .
GROUPID	Valeur <group_id> . Définissez le propriétaire du groupe du dossier Résultats sur <group_id> .
THREADS	Valeur <number_of_threads> . Utilisez autant de threads pour créer une base de données et évaluer les requêtes. Par défaut est 1. Vous pouvez passer 0 pour utiliser un thread par noyau sur la machine.
OVERWRITE_FLAG	Value --overwrite . Activer / désactiver la base de données d'écrasement lorsque le chemin de la base de données existe et non un répertoire vide. Ce drapeau est utile pour reconstruire de force la base de données.
QS	Valeur <queries-suite> . Spécifiez une liste de requêtes pour exécuter votre base de données. La valeur par défaut est <language>-security-extended.qls . Pour plus de détails, veuillez consulter l'analyse des bases de données avec la CLI CodeQL.
SAVE_CACHE_FLAG	Valeur --save-cache . Enregistrez agressivement les résultats intermédiaires du cache de disque. Cela peut accélérer les requêtes ultérieures si elles sont similaires. Sachez que l'utilisation de cette option augmentera considérablement l'utilisation du disque et le temps d'évaluation initial.
ACTION	Valeur create-database-only . Création de la base de données CodeQL uniquement sans exécuter l'analyse CodeQL.
COMMAND	Valeur <command> . La variable utilisée lorsque vous créez une base de données CodeQL pour une ou plusieurs langues compilées, omettez si les seules langues demandées sont Python et JavaScript. Cela spécifie les commandes de construction nécessaires pour invoquer le compilateur. Si vous ne définissez pas cette variable, CodeQL tentera de détecter automatiquement le système de construction, à l'aide d'un autobuilder intégré.

---

Avertissement: l'agent CodeQL transmet directement ces options aux arguments de commande lors de l'exécution du conteneur. Veuillez le prendre en tant que responsabilité de sécurité.

Exemples d'utilisation

Analyse de code de base.

docker run --rm --name codeql-agent-docker 
  -v " $PWD :/opt/src " 
  -v " $PWD /codeql-agent-results:/opt/results " 
  doublevkay/codeql-agent

Analyse de code avec des threads maximaux disponibles.

docker run --rm --name codeql-agent-docker 
  -v " $PWD :/opt/src " 
  -v " $PWD /codeql-agent-results:/opt/results " 
  -e " THREADS=0 " 
  doublevkay/codeql-agent

Créer une base de données uniquement.

docker run --rm --name codeql-agent-docker 
  -v " $PWD :/opt/src " 
  -v " $PWD /codeql-agent-results:/opt/results " 
  -e " ACTION=create-database-only " 
  doublevkay/codeql-agent

Spécifiez la suite de requêtes pour la source Java.

docker run --rm --name codeql-agent-docker 
  -v " $PWD :/opt/src " 
  -v " $PWD /codeql-agent-results:/opt/results " 
  -e " LANGUAGE=java " 
  -e " QS=java-security-and-quality.qls " 
  doublevkay/codeql-agent

Changer le propriétaire du dossier Résultats.

Parce que l'agent CodeQL exécute le script en tant que racine dans les conteneurs Docker. Alors peut-être que vous devez changer le propriétaire du dossier des résultats.

docker run --rm --name codeql-agent-docker 
  -v " $PWD :/opt/src " 
  -v " $PWD /codeql-agent-results:/opt/results " 
  -e " USERID= $( id -u ${USER} ) " -e " GROUPID= $( id -g ${USER} ) 
  doublevkay/codeql-agent

Spécifiez la version Java et la commande de base de données de construction

Par défaut, nous utilisons JDK 11 et Maven 3.6.3 pour l'image de l'agent CodeQL. Nous pouvons modifier les versions de Java et Maven en montant un volume et en définissant les variables d'environnement Java_Home et Maven_Home dans le conteneur d'agent CodeQL. Par exemple:

1. Créez un dockerfile (nommé dockerfile-java) pour les versions spécifiques de Java et Maven, et placez-la dans le répertoire qui sera utilisé pour le montage plus tard:

    FROM --platform=amd64 maven:3-jdk-8-slim
   
    RUN mkdir -p /opt/jdk/ /opt/maven/
   
    RUN cp -r $JAVA_HOME/* /opt/jdk/
   
    RUN cp -r $MAVEN_HOME/* /opt/maven/
   
    CMD [ "echo" ]

2. Construisez et exécutez le conteneur Docker, en montant les répertoires JDK et Maven aux volumes respectifs:

    docker buildx build -t codeql-java -f Dockerfile-java .
    docker run --rm  -v " jdkvol:/opt/jdk " -v " mavenvol:/opt/maven " codeql-java

3. Enfin, exécutez le conteneur CodeQL-Agent avec des volumes montés et définissez la variable Env Java_Home, Maven_Home aux volumes montés

docker run --rm --name codeql-agent-docker 
  -v " $PWD :/opt/src " 
  -v " $PWD /codeql-agent-results:/opt/results " 
  -v " jdkvol:/opt/jdk " 
  -v " mavenvol:/opt/maven " 
  -e " LANGUAGE=java " 
  -e " JAVA_HOME=/opt/jdk " 
  -e " MAVEN_HOME=/opt/maven " 
  -e " COMMAND=mvn clean install " 
  doublevkay/codeql-agent

Construire

Vous pouvez utiliser l'image de l'agent CodeQL sur Docker Hub ou personnaliser et la construire localement.

 # Build codeql-agent docker image locally 
cd codeql-agent
docker build -t codeql-agent . 

Comment ça marche?

L'agent CodeQL est une image Docker. Les étapes suivantes sont effectuées pour atteindre les objectifs d'automatisation de l'utilisation de CodeQL.

Configuration de l'environnement

Dans cette étape, l'image prépare l'environnement pour exécuter CodeQL. Il comprend: en utilisant l'image de base Ubuntu; Téléchargement et installation du bundle CodeQL (qui contient le CODEQL CLI et les requêtes de bibliothèque précompilées pour réduire le temps d'exécution CodeQL); Installation des logiciels nécessaires tels que java , maven , nodejs , typescript , ... pour créer une base de données CodeQL avec succès.

Détection de la langue

L'agent CodeQL utilise GitHub / Linguist pour détecter la langue du code source.

Création de base de données

L'agent CodeQL exécute la commande de base de données CodeQL Create.

codeql database create --threads= $THREADS --language= $LANGUAGE $COMMAND $DB -s $SRC $OVERWRITE_FLAG

Spécification des suites de requête

L'analyse de bases de données nécessite de spécifier une suite de requête. Selon les objectifs des objectifs des tests de sécurité des applications statiques (SAST), CodeQL Agent utilise <language>-security-extended.qls comme suite de requête par défaut.

Analyse de la base de données

L'agent CodeQL exécute la commande CodeQL Database Analysis.

codeql database analyze --format= $FORMAT --threads= $THREADS $SAVE_CACHE_FLAG --output= $OUTPUT /issues. $FORMAT $DB $QS

Format de résultats de conversion

L'agent CodeQL convertira le résultat CodeQL du format Sarif en schémas de rapport de sécurité (fourni par GitLab). Cette étape se fait en mappant les champs de deux formats. Les détails de l'implémentation sont dans le script SariF2Sast. Vous pouvez utiliser ce script indépendamment comme solution de contournement pour résoudre le problème de Gitlab 118496.

Crédits

Ce référentiel est basé sur Microsoft / CodeQL-Container et J3SSIE / CodeQL-Docker avec plus d'options de fonction. Spécifiquement:

• Améliorez la configuration de l'environnement pour augmenter la fiabilité.
• Détecter automatiquement la langue.
• Prise en charge des options de code ITT.
• Soutenez la langue java.

Soutien

Vous pouvez ouvrir un problème sur le repo github

Contributif

Les contributions sont toujours les bienvenues! Créez simplement une demande de traction ou contactez-moi

Contributeurs

Notes de libération

Voir les détails

Licence

L'agent CodeQL utilise CodeQL CLI comme moteur de base. Veuillez suivre les termes et conditions GitHub CodeQL et le prendre comme votre propre responsabilité.