Merge pull request #84 from angaduom/update-cve-fixer-docs

docs: add comprehensive team onboarding section to CVE Fixer workflow

Author: jwm4

workflows/cve-fixer/.ambient/ambient.json

@@ -1,8 +1,8 @@
 {
   "name": "CVE Fixer",
   "description": "Automate remediation of CVE issues reported by ProdSec team in Jira by creating pull requests with dependency updates and patches",
-  "systemPrompt": "You are a CVE remediation assistant for the Ambient Code Platform. Your role is to help users remediate CVE issues that have been reported by the ProdSec team in Jira by automatically creating pull requests with fixes.\n\nKEY RESPONSIBILITIES:\n- Guide users through the CVE remediation workflow for Jira-tracked vulnerabilities\n- Execute slash commands to perform specific security tasks\n- Find CVE issues opened by ProdSec team in Jira\n- Implement secure fixes that resolve vulnerabilities without breaking functionality\n- Create pull requests with dependency updates, patches, and comprehensive test results\n\nWORKFLOW METHODOLOGY:\n1. FIND - Find CVEs already reported in Jira for a component\n2. FIX - Implement remediation strategies (dependency updates, patches, code changes, PR creation)\n\nAVAILABLE COMMANDS:\n/cve.find - Find CVEs reported in Jira for a specific component\n/cve.fix - Implement fixes for discovered CVEs and create pull requests\n\nOUTPUT LOCATIONS:\n- Create all Jira CVE findings in: artifacts/cve-fixer/find/\n- Create all fix implementations in: artifacts/cve-fixer/fixes/\n\nFIRST TIME SETUP:\nBefore using any slash commands, ensure the workspace is initialized and security scanning tools are available.",
-  "startupPrompt": "Welcome! I'm your CVE Remediation assistant.\n\n🎯 WHAT I DO:\nI help you remediate CVE issues reported by the ProdSec team in Jira by automatically creating pull requests with dependency updates, patches, and code changes.\n\n📋 WORKFLOW PHASES:\n1. **Find** - Discover CVE issues opened by ProdSec in Jira for a component\n2. **Fix** - Implement secure remediations and create pull requests\n\n🚀 AVAILABLE COMMANDS:\n/cve.find - Find CVE issues reported by ProdSec in Jira\n/cve.fix - Implement security fixes and create PRs\n\n💡 GETTING STARTED:\nRun /cve.find to discover CVE issues from ProdSec in Jira for a specific component, then use /cve.fix to automatically remediate them with pull requests.\n\n**Note:** This workflow is designed for CVE issues tracked in Jira by your Product Security team.\n\nWhat would you like to accomplish today?",
+  "systemPrompt": "You are a CVE remediation assistant for the Ambient Code Platform. Your role is to help users remediate CVE issues that have been reported by the ProdSec team in Jira by automatically creating pull requests with fixes.\n\nKEY RESPONSIBILITIES:\n- Guide users through the CVE remediation workflow for Jira-tracked vulnerabilities\n- Execute slash commands to perform specific security tasks\n- Find CVE issues opened by ProdSec team in Jira\n- Implement secure fixes that resolve vulnerabilities without breaking functionality\n- Create pull requests with dependency updates, patches, and comprehensive test results\n\nWORKFLOW METHODOLOGY:\n1. FIND - Find CVEs already reported in Jira for a component\n2. FIX - Implement remediation strategies (dependency updates, patches, code changes, PR creation)\n\nAVAILABLE COMMANDS:\n/cve.find - Find CVEs reported in Jira for a specific component\n/cve.fix - Implement fixes for discovered CVEs and create pull requests\n\nOUTPUT LOCATIONS:\n- Create all Jira CVE findings in: artifacts/cve-fixer/find/\n- Create all fix implementations in: artifacts/cve-fixer/fixes/\n\nNote: Commands will guide you through required setup steps on first use. If the user's component is not in component-repository-mappings.json, direct them to the \"Team Onboarding\" section in README.md.",
+  "startupPrompt": "Welcome! I'm your CVE Remediation assistant.\n\n🎯 WHAT I DO:\nI help you remediate CVE issues reported by the ProdSec team in Jira by automatically creating pull requests with dependency updates, patches, and code changes.\n\n📋 WORKFLOW PHASES:\n1. **Find** - Discover CVE issues opened by ProdSec in Jira for a component\n2. **Fix** - Implement secure remediations and create pull requests\n\n🚀 AVAILABLE COMMANDS:\n/cve.find - Find CVE issues reported by ProdSec in Jira\n/cve.fix - Implement security fixes and create PRs\n\n💡 GETTING STARTED:\nRun /cve.find to discover CVE issues from ProdSec in Jira for a specific component, then use /cve.fix to automatically remediate them with pull requests.\n\nFirst time? See README.md → \"Team Onboarding\" for setup requirements.\n\nWhat would you like to accomplish today?",
   "results": {
     "Jira CVE Issues": "artifacts/cve-fixer/find/**/*.md",
     "Fix Implementations": "artifacts/cve-fixer/fixes/**/*"

workflows/cve-fixer/.claude/commands/cve.find.md

@@ -99,8 +99,26 @@ Report: artifacts/cve-fixer/find/cve-issues-20260226-145018.md
 
    b. Construct JQL query and execute API call:
    ```bash
+   # Normalize component name with case-insensitive lookup against mapping file
+   # Try relative to cwd (workflow root), then repo-relative fallback
+   if [ -f "component-repository-mappings.json" ]; then
+     MAPPING_FILE="component-repository-mappings.json"
+   elif [ -f "workflows/cve-fixer/component-repository-mappings.json" ]; then
+     MAPPING_FILE="workflows/cve-fixer/component-repository-mappings.json"
+   else
+     MAPPING_FILE=""
+   fi
+   if [ -n "$MAPPING_FILE" ] && [ -f "$MAPPING_FILE" ]; then
+     CANONICAL_NAME=$(jq -r --arg name "${COMPONENT_NAME}" \
+       '.components | keys[] | select(ascii_downcase == ($name | ascii_downcase))' \
+       "$MAPPING_FILE" | head -1)
+     if [ -n "$CANONICAL_NAME" ]; then
+       COMPONENT_NAME="$CANONICAL_NAME"
+     fi
+   fi
+
    # Build JQL query
-   JQL="project = RHOAIENG AND component = \"${COMPONENT_NAME}\" AND summary ~ \"CVE*\""
+   JQL="component = \"${COMPONENT_NAME}\" AND summary ~ \"CVE*\" AND labels = SecurityTracking"
 
    # Append resolved filter if --ignore-resolved flag was provided
    if [ "$IGNORE_RESOLVED" = "true" ]; then
@@ -332,7 +350,7 @@ Report: artifacts/cve-fixer/find/cve-issues-20260226-145018.md
    **Ignored Issues:** ${IGNORED_COUNT}
 
    ## Query Parameters
-   - **JQL Query:** project = RHOAIENG AND component = "${COMPONENT_NAME}" AND summary ~ "CVE*"$( [ "$IGNORE_RESOLVED" = "true" ] && echo ' AND status not in ("Resolved")' )
+   - **JQL Query:** component = "${COMPONENT_NAME}" AND summary ~ "CVE*" AND labels = SecurityTracking$( [ "$IGNORE_RESOLVED" = "true" ] && echo ' AND status not in ("Resolved")' )
    - **Columns:** KEY, SUMMARY, STATUS, PRIORITY, CREATED, COMPONENTS
    - **Jira Instance:** ${JIRA_BASE_URL}
 

workflows/cve-fixer/README.md

@@ -11,6 +11,139 @@ This workflow helps you remediate CVE vulnerabilities that have been reported by
 
 The workflow is designed for both interactive use and scheduled automation (GitHub Actions, Ambient scheduled sessions).
 
+## Team Onboarding
+
+**⚠️ IMPORTANT:** New teams must complete the onboarding process before using this workflow.
+
+### Onboarding Requirements
+
+Before your team can use the CVE Fixer workflow, the following setup must be completed:
+
+#### 1. Component-to-Repository Mapping
+
+Your team's Jira components must be mapped to GitHub repositories in `component-repository-mappings.json`.
+
+**What you need to provide:**
+- Jira component name (as it appears in your Jira project)
+- GitHub repository URLs (upstream, midstream, and/or downstream)
+- Default and active release branches for each repository
+
+**Example mapping:**
+```json
+{
+  "Your Component Name": {
+    "container_to_repo_mapping": {
+      "rhoai/odh-your-container-rhel9": "org/upstream-repo"
+    },
+    "repositories": {
+      "org/upstream-repo": {
+        "github_url": "https://github.com/org/upstream-repo",
+        "default_branch": "main",
+        "active_release_branches": ["release-1.0"],
+        "branch_strategy": "Fix in main. Release branches follow pattern release-X.Y.",
+        "repo_type": "upstream"
+      },
+      "org/downstream-repo": {
+        "github_url": "https://github.com/org/downstream-repo",
+        "default_branch": "main",
+        "active_release_branches": ["rhoai-3.4"],
+        "branch_strategy": "Fork of midstream. RHOAI release branches follow pattern rhoai-X.Y.",
+        "repo_type": "downstream"
+      }
+    }
+  }
+}
+```
+
+#### 2. ProdSec Team Coordination
+
+The Product Security (ProdSec) team must:
+- Create Jira component for your team in your Jira project
+- Configure CVE issue templates for your component
+- Set up automated CVE discovery and Jira issue creation
+
+**Contact:** Make sure your component repos are actively scanned by ProdSec team. If your component is not onboarded please follow the feature refinement process.
+
+#### 3. GitHub Access Configuration
+
+The workflow requires GitHub CLI (`gh`) authentication to create pull requests.
+
+**Required permissions:**
+- Read access to your upstream/downstream repositories
+- Write access (PR creation) to repositories where fixes will be applied
+- Ability to run `gh auth login` or use `GITHUB_TOKEN` environment variable
+
+**Setup:**
+```bash
+# Option 1: Interactive login
+gh auth login
+
+# Option 2: Use token (for automation)
+export GITHUB_TOKEN="your-personal-access-token"
+```
+
+#### 4. Jira API Access
+
+Each team member using the workflow needs:
+- Red Hat Jira account with access to your Jira project
+- Jira API token for authentication
+- Read access to CVE issues for their component
+
+**Setup:**
+1. Generate API token at https://id.atlassian.com/manage-profile/security/api-tokens
+2. Export credentials:
+   ```bash
+   export JIRA_API_TOKEN="your-token-here"
+   export JIRA_EMAIL="your-email@redhat.com"
+   ```
+
+### Onboarding Steps
+
+1. **Submit Onboarding Request**
+   - Contact the workflow maintainers with your component details
+   - Provide GitHub repository URLs and target branches
+   - Specify upstream/downstream repository structure
+
+2. **Wait for Mapping Update**
+   - Maintainers will add your component to `component-repository-mappings.json`
+   - PR will be created and merged
+   - You'll be notified when ready
+
+3. **Coordinate with ProdSec**
+   - Ensure your Jira component exists in your Jira project
+   - Verify CVE issues are being filed against your component
+   - Test with a sample CVE issue
+
+4. **Set Up Personal Credentials**
+   - Configure Jira API access (step 4 above)
+   - Configure GitHub access (step 3 above)
+   - Test with `/cve.find` command
+
+5. **Test Workflow**
+   - Run `/cve.find` for your component
+   - Review discovered issues
+   - Test `/cve.fix` on a non-critical CVE
+   - Verify PR creation and formatting
+
+### Onboarding Checklist
+
+Before using the workflow, verify:
+
+- [ ] Component mapped in `component-repository-mappings.json`
+- [ ] ProdSec filing CVEs against your Jira component
+- [ ] JIRA_API_TOKEN and JIRA_EMAIL configured
+- [ ] GitHub CLI authenticated (`gh auth status`)
+- [ ] Test repository access with `gh repo view <org/repo>`
+- [ ] Tested `/cve.find` returns issues for your component
+- [ ] Tested `/cve.fix` creates a PR successfully
+
+### Who to Contact
+
+- **Workflow Mapping Updates**: Open PR against this repository or contact workflow maintainers (@angaduom, @vmrh21)
+- **ProdSec Component Setup**: Contact your ProdSec team representative
+- **Jira Access Issues**: Contact Red Hat IT Support
+- **GitHub Access Issues**: Contact your GitHub org administrators
+
 ## Getting Started
 
 ### Prerequisites
@@ -104,18 +237,23 @@ The workflow uses `component-repository-mappings.json` to map Jira components to
 ```json
 {
   "Model as a Service": {
+    "container_to_repo_mapping": {
+      "rhoai/odh-maas-api-rhel9": "opendatahub-io/models-as-a-service"
+    },
     "repositories": {
       "opendatahub-io/models-as-a-service": {
         "github_url": "https://github.com/opendatahub-io/models-as-a-service",
-        "repo_type": "upstream",
-        "primary_target": "main",
-        "build_location": "."
+        "default_branch": "main",
+        "active_release_branches": [],
+        "branch_strategy": "Fix in main.",
+        "repo_type": "upstream"
       },
       "red-hat-data-services/models-as-a-service": {
         "github_url": "https://github.com/red-hat-data-services/models-as-a-service",
-        "repo_type": "downstream",
-        "primary_target": "rhoai-2.19",
-        "build_location": "."
+        "default_branch": "rhoai-3.0",
+        "active_release_branches": ["rhoai-3.0"],
+        "branch_strategy": "Fork of midstream. Fixes backported from upstream.",
+        "repo_type": "downstream"
       }
     }
   }