@conterra/vuln-scan 0.0.35 → 0.1.0

package/README.md

@@ -52,6 +52,10 @@ After that you have following commands available:
 - `ct-vuln-add-project-to-vex`
   - Update vex files to include a new project version. The project is added to each vex file that references the existing project version given.
   - This step is already included in the `ct-vuln-add-project` command, but it can be run separately to update the vex files for an already existing project entry in the configuration file.
+- `ct-vuln-jira-report`
+  - Reads a `scan-summary.json` produced by `ct-vuln-scan` and creates Jira issues for newly detected vulnerabilities.
+  - Issues are only created when no existing issue with the same vulnerability ID already exists in the target Jira project.
+  - Routing rules in a `jira.json` file control which scan projects are reported to which Jira projects.
 
 ### Vulnerability scan
 
@@ -489,6 +493,113 @@ $ ct-vuln-remove-project mapapps 4.18.3-SNAPSHOT
 $ ct-vuln-add-project mapapps 4.18.3 4.18.4-SNAPSHOT
 ```
 
+## Usage - Jira Report
+
+The `ct-vuln-jira-report` command reads the `scan-summary.json` produced by `ct-vuln-scan` and creates Jira issues for every new vulnerability that has not already been reported.
+
+For each vulnerability the tool:
+1. Checks (via JQL) whether an issue with the same vulnerability ID already exists in the target Jira project.
+2. If not, creates a new issue with a structured description including CVE details, affected artefacts, affected products, and placeholder sections for assessment and remediation.
+
+### Environment Variables
+
+```bash
+# Required
+JIRA_USER=user@example.com   # Jira account e-mail address
+JIRA_API_TOKEN=<token>       # Jira API token (https://id.atlassian.com/manage-profile/security/api-tokens)
+```
+
+NOTE: These variables can also be placed in a `.env` file in the working directory.
+
+### Configuration – `jira-conf.json`
+
+Create a `jira-conf.json` file (path is configurable) that defines the Jira instance and the routing rules:
+
+```json
+{
+  "$schema": "./node_modules/@conterra/vuln-scan/dist/schema/jira-config-schema.json",
+  "jiraUrl": "https://myorg.atlassian.net",
+  "issues": [
+    {
+      "jiraProject": "PLATFORM",
+      "issueType": "CVE",
+      "issueLabels": ["security"],
+      "addToBoard": [
+        {
+          "sprintBoardId": 10,
+          "issueLabels": ["team-a"],
+          "matchProjects": ["mapapps@*"]
+        },
+        {
+          "issueLabels": ["team-b"],
+          "matchProjects": ["smartfinder@*"]
+        }
+      ],
+      "reportProjects": [
+        "mapapps@*",
+        "smartfinder@4.*"
+      ]
+    },
+    {
+      "jiraProject": "OTHER",
+      "issueType": "Bug",
+      "reportProjects": ["*"]
+    }
+  ]
+}
+```
+
+| Field                        | Required | Description                                                                                                                                   |
+| ---------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `jiraUrl`                    | ✓        | Base URL of the Jira instance                                                                                                                 |
+| `issues`                     | ✓        | List of routing rules                                                                                                                         |
+| `issues[].jiraProject`       | ✓        | Jira project key, e.g. `PLATFORM`                                                                                                             |
+| `issues[].issueType`         | ✓        | Jira issue type name, e.g. `Bug`, `CVE`                                                                                                       |
+| `issues[].reportProjects`    | ✓        | Glob patterns (`*` wildcard) for scan project identifiers (`name@version`)                                                                    |
+| `issues[].issueLabels`       | –        | Global labels attached to every issue created by this rule, merged with any labels from `addToBoard` entries                                  |
+| `issues[].addToBoard`        | –        | Per-board routing rules (see table below). Enables Scrum sprint assignment and/or Kanban label routing                                        |
+| `addToBoard[].sprintBoardId` | –        | Scrum board ID. When set, the issue is assigned to the currently active sprint of that board via `customfield_10020`. Omit for Kanban boards. |
+| `addToBoard[].issueLabels`   | –        | Labels contributed by this board entry (see routing rules below)                                                                              |
+| `addToBoard[].matchProjects` | –        | Glob patterns to activate this entry. Defaults to `["*"]` (matches any project)                                                               |
+
+**`addToBoard` routing rules:**
+
+- Each entry in `addToBoard` is checked: its `matchProjects` patterns are tested against the scan projects affected by the current vulnerability. If none match, the entry is skipped.
+- **Scrum (sprintBoardId set):** The **first** matching entry with a `sprintBoardId` claims the sprint. All subsequent matching sprint entries – including their labels – are ignored. This avoids ambiguous multi-sprint assignments, which Jira does not support.
+- **Kanban (no sprintBoardId):** Matching entries always contribute their labels. This allows issues to appear on Kanban boards that filter by label.
+- The final label set on the created issue is: `issueLabels` (top-level) + labels from the winning sprint entry (if any) + labels from all matching Kanban entries.
+
+**`reportProjects` routing:** The `reportProjects` patterns are matched against each scan project identifier (`name@version`). The `*` wildcard matches any sequence of characters. Each routing rule is evaluated independently, so a vulnerability can be reported to multiple Jira projects. Rules that match no project are silently skipped.
+
+### CLI Usage
+
+```sh
+$ ct-vuln-jira-report [options]
+```
+
+```
+Options:
+  -c, --jira-config <path>   Path to jira-conf.json configuration file
+                             (default: ./jira-conf.json)
+  -s, --summary <path>       Path to scan-summary.json produced by ct-vuln-scan
+                             (default: ./output/scan-summary.json)
+      --dry-run              Print what would be created without calling Jira
+  -h, --help                 Show help
+```
+
+Examples:
+
+```sh
+# Use defaults (./jira-conf.json + ./output/scan-summary.json)
+$ ct-vuln-jira-report
+
+# Custom paths
+$ ct-vuln-jira-report --jira-config ./config/jira-conf.json --summary ./output/scan-summary.json
+
+# Preview without creating issues
+$ ct-vuln-jira-report --dry-run
+```
+
 ## Dev Notes
 
 Setup: