Minor edits, heading changes

Author: charlie-openai

examples/codex/secure_quality_gitlab.md

@@ -28,19 +28,21 @@ To follow along, you’ll need:
 * An **OpenAI API key** (`OPENAI_API_KEY`)  
 * GitLab CI/CD variables configured under **Settings → CI/CD → Variables**
 
-## **Problem Statement \#1 \- Code Quality**
+## **Example \#1 \- Using Codex CLI to Produce a Code Quality Report**
 
 ### Background
 
-This repository is a deliberately vulnerable Node.js Express demo app based on ([https://gitlab.com/gitlab-org/project-templates/express/-/tree/main](https://gitlab.com/gitlab-org/project-templates/express/-/tree/main))  built to showcase SAST and code quality scanning in GitLab CI/CD. The code includes common pitfalls such as command injection, path traversal, unsafe `eval`, regex DoS, weak cryptography (MD5), and hardcoded secrets. It’s used to validate that Codex-powered analyzers produce GitLab-native reports (Code Quality and SAST) that render directly in merge requests.
+This repository is a deliberately vulnerable Node.js Express demo app based on [GitLab's node express template](https://gitlab.com/gitlab-org/project-templates/express/-/tree/main), built to showcase static application security testing (SAST) and code quality scanning in GitLab CI/CD.
+
+The code includes common pitfalls such as command injection, path traversal, unsafe `eval`, regex DoS, weak cryptography (MD5), and hardcoded secrets. It’s used to validate that Codex-powered analyzers produce GitLab-native reports (Code Quality and SAST) that render directly in merge requests.
 
 The CI runs on GitLab SaaS runners with `node:24` images and a few extras (`jq`, `curl`, `ca-certificates`, `ajv-cli`). Jobs are hardened with `set -euo pipefail`, schema validation, and strict JSON markers to keep parsing reliable even if Codex output varies.
 
 This pipeline pattern—prompt, JSON marker extraction, schema validation—can be adapted to other stacks, though prompt wording and schema rules may need tweaks. Since Codex runs in a sandbox, some system commands (like `awk` or `nl`) may be restricted.
 
 Your team wants to ensure that **code quality checks run automatically** before any merge. To surface findings directly in GitLab’s merge request widget, reports must follow the **CodeClimate JSON format**. [Reference: GitLab Docs](https://docs.gitlab.com/ci/testing/code_quality/#import-code-quality-results-from-a-cicd-job)
 
-### CI/CD Job Example
+### Code Quality CI/CD Job Example
 
 Here’s a drop-in GitLab CI job using **Codex CLI** to produce a compliant JSON file:
 ```yaml
@@ -162,24 +164,24 @@ This approach has several benefits:
 
 As teams adopt this workflow, LLM-powered quality checks can complement traditional linting and vulnerability scanning—helping ensure that code shipped to production is both robust and maintainable.
 
-## **Problem Statement \#2 – Security Remediation**
+## **Example \#2 – Using Codex CLI for Security Remediation**
 
 ### Background
 
-For this problem statement we tested on [OWASP Juice Shop](https://github.com/juice-shop/juice-shop?utm_source=chatgpt.com), a deliberately vulnerable Node.js Express app. It contains common flaws such as injection, unsafe `eval`, weak crypto, and hardcoded secrets—ideal for validating Codex-powered analysis. 
+For this example, we tested on [OWASP Juice Shop](https://github.com/juice-shop/juice-shop?utm_source=chatgpt.com), a deliberately vulnerable Node.js Express app. It contains common flaws such as injection, unsafe `eval`, weak crypto, and hardcoded secrets—ideal for validating Codex-powered analysis. 
 
 Your team wants to ensure that whenever code changes are introduced, the pipeline automatically checks for security vulnerabilities before merge. This is already handled by static analyzers and language-specific scanners, which generate reports in the GitLab SAST JSON schema. However, raw outputs can be rigid, noisy, and often leave reviewers without clear next steps.
 
 By adding Codex CLI into your pipeline, you can turn scanner results generated by [GitLab SAST scanners](https://docs.gitlab.com/user/application_security/sast/) (or other scanner outputs) into **actionable remediation guidance** and even generate **ready-to-apply git patches**:
 
-### Recommendations stage
+### Step 1: Generating Recommendations
 
 * Codex reads `gl-sast-report.json`.  
 * Consolidates duplicate findings.  
 * Ranks by exploitability (e.g. user input → dangerous sinks).  
 * Produces a succinct `security_priority.md` with top 5 actions and detailed remediation notes.
 
-#### CI/CD Job Example
+#### Security Recommendations CI/CD Job Example
 
 **Requirement**: This job expects that upstream SAST jobs already generated a `gl-sast-report.json`. Codex reads it and produces `security_priority.md` for reviewers.
 
@@ -300,9 +302,9 @@ codex_recommendations:
      - security_priority.md
    expire_in: 14 days
 ```
-The output results look like this 
+Here's an example of the output we receive: 
 
-# Consolidated SAST Findings
+# Example Output: Consolidated SAST Findings
 
 Parsed `gl-sast-report.json` and merged overlapping issues.  
 **Total raw findings:** 5 → **Consolidated into:** 4 representative entries  
@@ -360,15 +362,15 @@ Parsed `gl-sast-report.json` and merged overlapping issues.
 - Owners/Teams: Backend/API (routes)  
 - References: OWASP SSRF Prevention; OWASP Top 10 A10:2021  
 ---
-### Remediation Stage Workflow
+### Step 2: Remediating Security Issues Based on Recommendations
 - Codex consumes both the SAST JSON and the repo tree.  
 - For each High/Critical issue:  
   - Builds a structured prompt → outputs a unified `git diff`.  
   - Diff is validated (`git apply --check`) before being stored as `.patch`.  
 
-### CI/CD Job Example
+#### Remediation CI/CD Job Example
 
-**Requirement**: This job depends on the previous stage output of the `security_priority.md` file to use as input to generate the patch file for creating an MR 
+**Requirement**: This job depends on the previous stage output of the `security_priority.md` file to use as input to generate the patch file for creating an MR: 
 ```yaml
  stages:
   - remediation
@@ -519,7 +521,7 @@ codex_resolution:
     expire_in: 14 days
 ```
 
-Example generated patch:
+Running the CI/CD job with Codex CLI, we receive a Git patch that fixes the issues originally found by our security scanner:
 
 ```patch
 <unified diff here>
@@ -576,12 +578,13 @@ export function profileImageUrlUpload () {
         return
 ```
 
-## **Why Does It Matters?**
+## Key Benefits
+Using Codex CLI in GitLab CI/CD allows you to augment existing review processes so that your team can ship faster.
 
-* **Keeps existing scanners as the source of truth**: No changes to how vulnerabilities are detected.  
+* **Complementary**: Codex doesn’t replace scanners — it interprets their findings and accelerates fixes. 
 * **Actionable**: Reviewers see not just vulnerabilities, but prioritized steps to fix them.  
 * **Automated**: Patches are created directly in CI, ready for `git apply` or a remediation branch.  
-* **Complementary**: Codex doesn’t replace scanners — it interprets their findings and accelerates fixes.
+
 ---
 
 ## **Wrapping Up**