تدقيق الكود وتوليد التقارير

إعداد البيئة

1. استنسخ مستودع Galaxium Travels.

   git clone -b bob-learning-path-branch https://github.com/IBM/galaxium-travels

2. انقر على File ثم Open Folder.

3. انتقل إلى مجلد galaxium-travels الذي استنسخته وافتحه.

4. افتح واجهة دردشة Bob بالنقر على أيقونة Bob بجانب شريط التنقل، أو استخدم الاختصار Option + Command + B (macOS) أو Ctrl + Alt + B (Windows).

5. في حقل إدخال الدردشة، نفّذ /init لتهيئة بيئة التطوير وإنشاء ملفات AGENTS.md لـ Bob. انقر على Approve todo tools for task إذا طُلب ذلك.

إنشاء مهارة تدقيق

أنشئ مهارة، وهي مجموعة تعليمات قابلة لإعادة الاستخدام يستخدمها Bob للتعامل مع مهمة محددة.

المهارة التالية تدقق قاعدة كود Galaxium Travels مقابل متطلبات OWASP ASVS المستوى 1.

تتحقق المهارة من الضوابط التالية:

1. تحت واجهة الدردشة، انقر على Bob - Settings، ثم انقر على Bob Settings.

2. انقر على Skills في الشريط الجانبي الأيسر.

3. انقر على زر + لإنشاء مهارة جديدة.

4. أدخل asvs-audit في حقل Skill Name. هذا هو الاسم المستخدم لاستدعاء المهارة بـ /asvs-audit في الدردشة.

5. أدخل وصفاً قصيراً في حقل Description:

   Audits a codebase against OWASP ASVS Level 1 access control, input validation, API security, and configuration requirements.

6. تأكد من تشغيل مبدّل Allow Bob to use this skill.

   مع تشغيل المبدّل، يمكن لـ Bob تفعيل المهارة من تلقاء نفسه عندما يستدعيها طلب أو خطة. خطة التدقيق التي ستنشئها لاحقاً في هذا الدرس تفعل ذلك بالضبط.

7. غيّر Scope & Location إلى galaxium-travels.

   يحفظ هذا المهارة في مجلد .bob/skills/ بالمشروع، بحيث تكون متاحة فقط في هذا المشروع ويمكن لفريقك التحكم في إصدارها مع قاعدة الكود. الموقع العام (~/.bob/skills/) سيجعل المهارة متاحة في كل مشروع على جهازك.

8. أدخل المهارة التالية في مربع نص Skill Instructions.

   ---
   name: asvs-audit
   description: Audit a codebase against OWASP ASVS Level 1 access control, input validation, API security, and configuration requirements and produce structured findings ready for SARIF and OSCAL export.
   user-invocable: true
   ---
   
   Perform a structured security audit of this codebase. Work through the following phases in order. Do not skip phases or combine them.
   
   ## Phase 1: Discover
   
   Read and understand the application before auditing. Focus on:
   - Entry points: main files, route definitions, controllers
   - Authentication and session handling code
   - Input validation and sanitization code
   - Database query code
   - Any files flagged as high-risk in earlier analysis
   
   Summarize what you find before proceeding to Phase 2.
   
   ## Phase 2: Audit
   
   Check each control below. For each one record: PASS, FAIL, or N/A.
   For every FAIL, record the file path and line number.
   
   ### V4.1 General Access Control
   - V4.1.3 — Users can only access their own resources; other users' data is not accessible
   - V4.1.5 — Access control denies by default — unauthenticated requests are rejected
   
   ### V4.2 Operation Level Access Control
   - V4.2.1 — Sensitive resources cannot be accessed by manipulating a predictable object ID (IDOR protection)
   
   ### V5.1 Input Validation
   - V5.1.1 — All string inputs have defined maximum length constraints
   
   ### V13.1 Generic Web Service Security
   - V13.1.3 — API endpoints do not accept credentials or PII in URL query parameters
   
   ### V14.4 HTTP Security Headers
   - V14.4.1 — HTTP responses include appropriate security headers such as Content-Security-Policy, X-Frame-Options, and X-Content-Type-Options
   
   ### V14.5 HTTP Request Header Validation
   - V14.5.3 — CORS origin is validated against an explicit allowlist — wildcard origins are not permitted
   
   ## Phase 3: Generate Findings
   
   For each FAIL, produce a finding in this format:
   
   **Finding [N]:**
   - Rule: ASVS [control number]
   - Severity: Critical / High / Medium / Low
   - File: [path]
   - Line: [number or range, if identifiable]
   - Issue: [one sentence describing what was found]
   - Fix: [one sentence describing the recommended change]
   
   ## Phase 4: Summary
   
   Produce a short summary:
   - Total controls checked
   - Pass / Fail / N/A counts
   - Two-sentence overall security posture assessment
   
   Save the findings to the location specified by the plan or prompt that invoked this skill. Do not generate SARIF, OSCAL, or other report files — report generation is a separate task. Report that the audit is complete and wait for the next instruction.

   هذه هي مجموعة التعليمات الكاملة التي يتبعها Bob أثناء التدقيق.

9. انقر على Create.

إيجاد المناطق عالية المخاطر للتدقيق

لتوفير الـ tokens، اطلب من Bob تحديد الملفات والمجلدات الأكثر صلة بالأمان. ستشغّل مهارة التدقيق على هذه المناطق.

1. إذا لم تكن لوحة الدردشة مفتوحة بالفعل، افتحها بـ Option + Command + B (macOS) أو Ctrl + Alt + B (Windows).

2. اختر Ask من محدد الوضع.

   كل وضع له قدرات وأساليب تفكير مختلفة. وضع Ask الأنسب للأسئلة والتحليل، لكن لا يمكنك كتابة أو تعديل الملفات في وضع Ask.

3. في حقل إدخال الدردشة، أدخل الطلب التالي لاستكشاف قاعدة الكود وإيجاد أعلى مناطق المخاطر الأمنية:

   Explore this codebase as a Senior Security Analyst. Give me a short summary covering:
   
   1. The primary tech stack and framework
   2. Identify the files and folders most relevant to security
   
   Make sure to also review:
   1. How authentication and session management are handled
   2. How user input is accepted and validated
   3. Where database queries are made
   4. Any API endpoints that accept external input
   
   I want to understand the highest security risk areas before running an audit.

   يقرأ Bob الملفات ويستجيب بملخص لهيكل التطبيق.

إنشاء خطة لتدقيق المناطق عالية المخاطر

أنشئ خطة لـ Bob ليتبعها عند تدقيق المناطق عالية المخاطر.

1. بدّل إلى وضع Plan.

2. اطلب من Bob إنشاء خطة لتدقيق المناطق عالية المخاطر. انقر على Approve todo tools for task إذا طُلب ذلك.

   Create a plan for auditing the high-risk areas found in the previous
   exploration.
   
   When auditing, use the asvs-audit skill to guide the process.
   
   When the plan runs, create the security/ directory if it does not exist and
   save the findings to security/audit-findings.md
   
   Save the plan to plan/audit-plan.md

3. قد يطرح Bob أسئلة متابعة لتوضيح نطاق التدقيق أو المناطق المحددة التي يجب التركيز عليها. يمكنك الإجابة عليها أو إخبار Bob بـ use your recommendation.

4. افتح ملف الخطة لفهم نهج التدقيق وما سيفعله Bob عند تشغيله.

تدقيق قاعدة الكود

1. انقر على زر + لبدء مهمة جديدة.

2. تأكد من أنك في وضع Agent في واجهة الدردشة.

   وضع Agent يمنح Bob قدرات كاملة، بما في ذلك كتابة الملفات والتنفيذ. هذا ضروري لمراحل التدقيق وتوليد التقارير.

3. انقر على محدد Permissions في واجهة الدردشة وتحقق من مربعات Read وEdit وExecute وSkill. اترك جميع المبدّلات الأخرى غير محددة لهذه المهمة.

   الصلاحية	الحالة	السبب
   Read	✅ مفعّل	Bob يقرأ قاعدة الكود وخطة التدقيق والمهارة
   Edit	✅ مفعّل	Bob يكتب النتائج إلى security/audit-findings.md
   Execute	✅ مفعّل	قد يشغّل Bob أوامر shell لحل المسارات أو تأكيد هيكل الملف
   Skill	✅ مفعّل	خطة التدقيق تستدعي مهارة asvs-audit
   MCP	❌ متوقف	غير مطلوب لتحليل الكود المحلي

4. اطلب من Bob تنفيذ خطة التدقيق.

   Implement the @plan/audit-plan.md

5. راجع النتائج في security/audit-findings.md.

   تخبر الخطة Bob بإنشاء مجلد security/ إذا لم يكن موجوداً وحفظ النتائج في security/audit-findings.md.

   حفظ النتائج يسمح لك ببدء دردشة جديدة مع نموذج باستخدام نافذة سياق جديدة. يمكنك توجيه Bob نحو ملف النتائج لتوليد التقارير دون إعادة قراءة كامل قاعدة الكود وتعليمات المهارة، مما يحافظ على نافذة السياق لتوليد التقارير.

   ملاحظة حول نافذة السياق: جميع النماذج لها نافذة سياق محددة. عند تدقيق قاعدة كود كبيرة، قد تتجاوز نافذة سياق النموذج. لقواعد الكود الكبيرة، جرّب تدقيق فئة ASVS واحدة في كل مرة. شغّل V4 أولاً، ثم V5 وV13 وV14، واطلب من Bob دمج النتائج في النهاية. هذا أيضاً سبب جيد للحفاظ على إيجاز SKILL.md واستخدام mentions السياق @ المحددة بدلاً من توجيه Bob نحو كامل المستودع دفعة واحدة.

توليد تقارير الأمان

SARIF هو تنسيق التبادل القياسي لنتائج التحليل الثابت. بيئات التطوير بما فيها Bob وGitHub Advanced Security ومعظم pipelines الـ CI/CD يمكنها استهلاك ملفات SARIF مباشرةً.

1. انقر على زر + لبدء مهمة جديدة.

2. تأكد من استخدام وضع Agent.

3. انقر على Permissions في لوحة الدردشة وتحقق من مربعات Read وEdit وExecute. اترك جميع المبدّلات الأخرى غير محددة لهذه المهمة.

   الصلاحية	الحالة	السبب
   Read	✅ مفعّل	Bob يقرأ النتائج في security/audit-findings.md
   Edit	✅ مفعّل	Bob يكتب تقرير SARIF إلى مجلد security/
   Execute	✅ مفعّل	قد يشغّل Bob أوامر shell لحل المسارات أو تأكيد هيكل الملف
   Skill	❌ متوقف	غير مطلوب لتوليد التقارير. المهارة أنشأت بالفعل النتائج التي يحتاجها الوكيل
   MCP	❌ متوقف	غير مطلوب لتحليل الكود المحلي

4. اطلب من Bob توليد تقرير SARIF باستخدام mention سياق @.

   @security/audit-findings.md
   
   Generate a SARIF 2.1.0 report from the audit findings.
   
   Save it to `security/audit-results.sarif`.
   
   Include:
   - Tool name: "ASVS Security Audit"
   - A rule entry for each ASVS control that was checked, with the control ID and description
   - A result entry for each finding, with severity level, file path, line number, and the fix recommendation in the message field

   يولّد Bob الملف ويحفظه في security/audit-results.sarif. تأكد من احتواء الملف على مصفوفة runs مع مدخلات results، واحدة لكل نتيجة من نتائج التدقيق.

   يبلّغ Bob أيضاً عن قرارات التخطيط التي اتخذها في الدردشة:

   مثال على المخرجات:

   Severity mapping used: Critical/High → SARIF error; Medium/Low → SARIF warning.
   The message.text for each result contains the full issue description and the fix
   recommendation in one field, so tooling that renders SARIF (GitHub Code
   Scanning, VS Code SARIF Viewer, etc.) will surface the remediation guidance
   inline.

5. افتح security/audit-results.sarif في Bob لمراجعة النتائج. يمكنك استخدام هذا الملف في أدوات أخرى مثل GitHub Advanced Security أو pipeline الـ CI/CD لعرض نتائج التدقيق.

توليد خطة معالجة OSCAL (POA&M)

POA&M الـ OSCAL هو مستند JSON قابل للقراءة آلياً يربط كل نتيجة بمهمة معالجة منظمة تحتوي على معلومات المخاطر وإرشادات التنفيذ وتعيينات المعالم. يمكن لـ Bob قراءة هذا الملف كقائمة عمل. يعمل خلال كل عنصر، يطبق الإصلاحات، ويضع علامة على المعالم المكتملة أثناء التقدم.

1. انقر على زر + لبدء مهمة جديدة.

2. انقر على قائمة الوضع في لوحة الدردشة واختر Agent.

3. انقر على Permissions في لوحة الدردشة وتحقق من مربعات Read وEdit وExecute. اترك جميع المبدّلات الأخرى غير محددة لهذه المهمة.

   الصلاحية	الحالة	السبب
   Read	✅ مفعّل	Bob يقرأ النتائج في security/audit-findings.md
   Edit	✅ مفعّل	Bob يكتب POA&M OSCAL إلى مجلد security/
   Execute	✅ مفعّل	قد يشغّل Bob أوامر shell لحل المسارات أو تأكيد هيكل الملف
   Skill	❌ متوقف	غير مطلوب لتوليد التقارير. المهارة أنشأت بالفعل النتائج التي يحتاجها الوكيل
   MCP	❌ متوقف	غير مطلوب لتحليل الكود المحلي

4. اطلب من Bob توليد تقرير POA&M OSCAL باستخدام mention سياق @.

   @security/audit-findings.md
   
   Generate an OSCAL Plan of Action and Milestones (POA&M) from the audit findings.
   
   Save it to `security/poam.json`.
   
   For each finding include:
   - A unique UUID
   - The ASVS control ID as the finding reference
   - Severity and a one-sentence risk description
   - A concrete remediation task with enough detail for an AI agent to implement it without additional context — include file path, line reference, and the specific change required
   - A milestone label based on severity: Critical and High findings get "sprint-1", Medium and Low get "sprint-2"
   
   Use OSCAL version 1.1.2 structure.

   يولّد Bob الملف ويحفظه في security/poam.json.

   مثال على المخرجات:

   Each poam-item contains:
   
   props — severity, asvs-control, and milestone label
   risks[] — one risk with a uuid, title, one-sentence risk description, and status: "open"
   
   remediations[] — one remediation with a lifecycle: "planned" flag, a title, and a description 
   that is specific enough for an AI agent to implement without additional context 
   (includes exact file paths, line numbers, and the concrete code change required)
   
   tasks[] — one or more discrete action tasks under each remediation (e.g. the IDOR finding breaks 
   out the short-term ownership check and the long-term UUID migration as separate tasks)

لديك الآن نتيجتان في مجلد security/:

• audit-results.sarif — نتائج منظمة لأدوات المطور وتكامل CI/CD
• poam.json — قائمة عمل معالجة للمعالجة المدعومة بالذكاء الاصطناعي أو البشرية

مراجعة النتائج

مع توليد POA&M، راجع النتائج وحدد الأولويات لما يجب إصلاحه أولاً.

1. انقر على زر + لبدء مهمة جديدة.

2. انقر على قائمة الوضع في لوحة الدردشة واختر Ask.

3. اطلب من Bob تسليط الضوء على أهم العناصر من POA&M باستخدام mention سياق @.

   @security/poam.json
   
   Review this remediation plan and identify the 3 most critical items to fix first.
   
   For each one include:
   - What the vulnerability is and why it is the highest priority
   - Which file and line to look at
   - What the fix involves and roughly how long it would take a developer to implement

   يقرأ Bob الملف ويعيد ملخصاً مرتباً حسب الأولوية.

   يمكنك أيضاً دمج خادم بروتوكول سياق النموذج (MCP) في سير عمل تدقيقك وطلب من Bob إنشاء تذاكر لكل نتيجة، مع ربطها بالكود ذي الصلة وتضمين إرشادات المعالجة من POA&M.