@conterra/vuln-scan 0.0.34 → 0.0.36

package/README.md

@@ -49,6 +49,13 @@ After that you have following commands available:
 - `ct-vuln-remove-project`
   - Removes a project from the configuration file and all vex statements related to the project.
   - Or removes a project from all vex statements matching a given vulnerability id.
+- `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
 
@@ -457,6 +464,22 @@ $ ct-vuln-remove-project mapapps 4.18.2-SNAPSHOT CVE-2024-38820
 This will remove the product-id from all vex statements matching the given vulnerability.
 This is useful if a vulnerability is no longer detected for a project and you like to remove an existing statement.
 
+## Usage - Add project to vex
+Adds a new project version to all vex statements matching a reference project version.
+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.
+
+To update vex files to include a new project version, run:
+
+```sh
+$ ct-vuln-add-project-to-vex <existingPurl> <newPurl>
+```
+
+for example:
+
+```sh
+$ ct-vuln-add-project-to-vex pkg:maven/de.conterra.mapapps/ct-mapapps@4.19.0 pkg:maven/de.conterra.mapapps/ct-mapapps@4.19.1
+```
+
 ## Usage - Simulate a version release with preparation of the next dev version
 
 By combining the `ct-vuln-add-project` and `ct-vuln-remove-project` commands, you can simulate a version release.
@@ -470,6 +493,116 @@ $ 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.json`
+
+Create a `jira.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", "cve"],
+      "boardId": 12,
+      "assignToActiveSprint": true,
+      "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`          | –        | Labels to attach to every created issue                                                                                                                                                  |
+| `issues[].boardId`              | –        | Scrum board ID – needed to resolve the active sprint                                                                                                                                     |
+| `issues[].assignToActiveSprint` | –        | When `true` and `boardId` is set, the issue is added to the currently active sprint. If no sprint is found or the API call fails the issue is still created without a sprint assignment. |
+
+**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.json configuration file
+                             (default: ./jira.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.json + ./output/scan-summary.json)
+$ ct-vuln-jira-report
+
+# Custom paths
+$ ct-vuln-jira-report --jira-config ./config/jira.json --summary ./output/scan-summary.json
+
+# Preview without creating issues
+$ ct-vuln-jira-report --dry-run
+```
+
+### Issue Title Format
+
+```
+[<SEVERITY>] <Vuln-Id>: <Vuln-Title>
+```
+
+Example: `[HIGH] CVE-2024-0001: Remote code execution in foo-lib`
+
+### Issue Description Structure
+
+Each created issue contains the following sections (in Jira ADF format):
+
+| Section                  | Content                                                   |
+| ------------------------ | --------------------------------------------------------- |
+| **CVE Info**             | Vulnerability description and dependency tree (ASCII art) |
+| **Betroffene Artefakte** | List of affected component purls                          |
+| **Gemeldete Produkte**   | Scan projects matched by this routing rule                |
+| **Einwertung**           | Placeholder for severity/impact assessment                |
+| **Betroffene Produkte**  | Placeholder for final affected/not-affected determination |
+| **Maßnahmen**            | Placeholder for remediation steps                         |
+
 ## Dev Notes
 
 Setup: