codeql agent docker

وكيل CODEQL لـ Docker

CodeQL Agent هو مشروع يهدف إلى أتمتة استخدام CodeQL. يساعد المشروع في إنشاء قاعدة البيانات وتنفيذ تحليل CODEQL. CodeQl Agent هو صورة Docker.

CodeQL Agent for Docker هو أيضًا الصورة الأساسية لوكيل CodeQL لرمز Visual Studio - امتداد لرمز Visual Studio الذي يبسط استخدام CodeQL ويقوم بتنفيذ الكود المسح التلقائي.

يتم إصدار صورة Agent CodeQl على Docker Hub تحت اسم doublevkay/codeql-agent . يمكنك استخدامه دون بناء محليا.

محتويات:

• ما هذا؟
• ابدء
• أمثلة استخدام
• الخيارات المدعومة
• يبني
• كيف تعمل؟
• يدعم
• المساهمة
• المساهمين
• ملاحظات الإصدار
• رخصة

ما هذا؟

يوفر وكيل CodeQL لـ Docker هذه الميزات الرئيسية:

• اكتشاف اللغة تلقائيًا.
• إنشاء قاعدة بيانات CODEQL.
• تنفيذ تحليل قاعدة بيانات CODEQL.
• تلقائي مزامنة أحدث إصدار من مكتبة CodeQl CLI و CodeQL.

ابدء

قم بربط المصدر ، ومجلد النتائج وصورة codeql-agent مع أمر Docker التالي.

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

يمكنك أيضًا تحديد المزيد من الخيارات لتشغيل وكيل CodeQL. انظر الخيارات المدعومة لمزيد من التفاصيل.

الخيارات المدعومة

يمكنك تعيين متغيرات البيئة لاستخدام الخيارات المدعومة التالية:

عامل	وصف
LANGUAGE	القيمة <language> . اضبط لغة المشروع لإنشاء قاعدة بيانات أو تنفيذ SAST. يجب أن يكون <language> : go ، java ، cpp ، csharp ، python ، javascript ، ruby .
USERID	القيمة <id> . اضبط مالك المجلد على النتائج على <id> .
GROUPID	القيمة <group_id> . قم بتعيين مالك المجموعة لمجلد النتائج على <group_id> .
THREADS	القيمة <number_of_threads> . استخدم هذه الخيوط العديدة لإنشاء قاعدة بيانات وتقييم الاستعلامات. الإعدادات الافتراضية إلى 1. يمكنك تمرير 0 لاستخدام مؤشر ترابط واحد لكل قلب على الجهاز.
OVERWRITE_FLAG	القيمة --overwrite . تمكين/تعطيل قاعدة بيانات الكتابة فوق عند وجود مسار قاعدة البيانات وليس دليلًا فارغًا. هذا العلم مفيد لإعادة بناء قاعدة البيانات بالقوة.
QS	القيمة <queries-suite> . حدد قائمة بالاستعلامات لتشغيلها على قاعدة البيانات الخاصة بك. القيمة الافتراضية هي <language>-security-extended.qls . QLS. لمزيد من التفاصيل ، يرجى الاطلاع على تحليل قواعد البيانات مع CODEQL CLI.
SAVE_CACHE_FLAG	القيمة --save-cache . حفظ بقوة النتائج الوسيطة إلى ذاكرة التخزين المؤقت للقرص. قد يؤدي هذا إلى تسريع الاستعلامات اللاحقة إذا كانت متشابهة. انتبه إلى أن استخدام هذا الخيار سيزيد بشكل كبير من استخدام القرص ووقت التقييم الأولي.
ACTION	القيمة create-database-only . إنشاء قاعدة بيانات CODEQL فقط دون تنفيذ تحليل CODEQL.
COMMAND	القيمة <command> . المتغير المستخدم عند إنشاء قاعدة بيانات CODEQL لمغادرة واحدة أو أكثر من اللغات المترجمة ، ما إذا كانت اللغات الوحيدة المطلوبة هي Python و JavaScript. هذا يحدد أوامر الإنشاء اللازمة لاستدعاء المترجم. إذا لم تقم بتعيين هذا المتغير ، فسيحاول CodeQL اكتشاف نظام الإنشاء تلقائيًا ، باستخدام Autobuilder مدمج.

---

إخلاء المسئولية: يقوم وكيل CODEQL بإعادة توجيه هذه الخيارات مباشرة إلى وسيطات الأوامر أثناء تشغيل الحاوية. يرجى أخذها كمسؤولية أمنية.

أمثلة استخدام

مسح الكود الأساسي.

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

كود المسح مع أقصى مؤشرات الترابط المتاحة.

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

إنشاء قاعدة بيانات فقط.

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

حدد جناح الاستعلامات لمصدر 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

تغيير مالك مجلد النتائج.

لأن Agent CodeQL يقوم بتشغيل البرنامج النصي كجذر في حاويات Docker. لذلك ربما تحتاج إلى تغيير مالك مجلد النتائج إلى نفسه.

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

حدد إصدار Java وأمر Build Database

بشكل افتراضي ، نستخدم JDK 11 و Maven 3.6.3 لصورة Agent CodeQL. يمكننا تغيير إصدارات Java و Maven عن طريق تركيب وحدة التخزين ووضع متغيرات بيئة Java_Home و Maven_Home في حاوية وكيل CodeQL. على سبيل المثال:

1. إنشاء dockerfile (اسمه Dockerfile-java) للإصدارات المحددة من Java و Maven ، ووضعها في الدليل الذي سيتم استخدامه للتصاعد لاحقًا:

    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. قم ببناء وتشغيل حاوية Docker ، وتركيب أدلة JDK و Maven إلى المجلدات المعنية:

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

3. أخيرًا ، حاوية Run CodeQL-Agent مع أحجام مثبتة ومجموعة ENV متغير Java_home ، maven_home إلى المجلدات المثبتة

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

يبني

يمكنك استخدام صورة Agent CodeQL على Docker Hub أو تخصيصها وإنشائها محليًا.

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

كيف تعمل؟

CodeQl Agent هو صورة Docker. تتم الخطوات التالية لتحقيق أهداف استخدام استخدام CODEQL.

إعداد البيئة

في هذه الخطوة ، تقوم الصورة بإعداد البيئة لتنفيذ CodeQL. ويشمل: استخدام صورة أساسية Ubuntu ؛ تنزيل وتثبيت حزمة CodeQL (التي تحتوي على CODEQL CLI واستعلامات المكتبة المسبقة لتقليل وقت تنفيذ CODEQL) ؛ تثبيت البرامج اللازمة مثل java و maven و nodejs و typescript و ... لإنشاء قاعدة بيانات CODEQL بنجاح.

الكشف عن اللغة

يستخدم Agent CodeQL GitHub/Linguist للكشف عن لغة الكود المصدر.

إنشاء قاعدة بيانات

يقوم Agent CodeQL بتشغيل الأمر CODEQL إنشاء قاعدة بيانات.

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

تحديد أجنحة الاستعلام

يتطلب تحليل قواعد البيانات تحديد مجموعة استعلام. وفقًا لأهداف Application Application Static Application Security Test (SAST) ، يستخدم Agent CodeQL <language>-security-extended.qls كجناح الاستعلام الافتراضي.

تحليل قاعدة البيانات

يقوم Agent CodeQL بتشغيل أمر تحليل قاعدة بيانات CODEQL.

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

تحويل تنسيق نتيجة

سيقوم وكيل CODEQL بتحويل نتيجة CODEQL من تنسيق SARIF إلى مخططات تقرير الأمان (المقدمة من GITLAB). تتم هذه الخطوة عن طريق تعيين حقول تنسيقين. تفاصيل التنفيذ موجودة في نص SARIF2SAST. يمكنك استخدام هذا البرنامج النصي بشكل مستقل كحل لحل قضية Gitlab 118496.

الاعتمادات

يعتمد هذا الريبو على Microsoft/CodeQl-Container و J3SSIE/CodeQL-Docker مع المزيد من خيارات الوظائف. خاصة:

• تعزيز إعداد البيئة لزيادة الموثوقية.
• الكشف تلقائيا اللغة.
• دعم خيارات CodeQL المفيدة.
• دعم لغة جافا.

يدعم

يمكنك فتح مشكلة على Github Repo

المساهمة

المساهمات دائما موضع ترحيب! فقط قم بإنشاء طلب سحب أو اتصل بي

المساهمين

ملاحظات الإصدار

انظر التفاصيل

رخصة

CodeQl Agent هو استخدام CodeQl CLI كمحرك أساسي. يرجى اتباع شروط وأحكام GitHub CodeQL واتخاذها كمسؤوليتك الخاصة.