Dr.Egeria survey report and security finding commands (Egeria 6.3)

EGERIA_OPEN_ISSUES.md

@@ -54,6 +54,8 @@ So "never set" and "set to 0 / false" come back identical. Confirmed live on 202
 
 **Question for the Egeria team (Mandy):** could these become boxed types (`Float`, `Boolean`, `Long`, `Integer`) with a `null` default, so that an unset value is omitted from the response? `cvssScore` matters most: a CVSS score of 0.0 is a real rating (severity "None").
 
+**Addendum 2026-10-26 (later the same day): a merge update wipes these fields.** While live-testing the Dr.Egeria finding commands (step 4), a `PenetrationTestFindingAnnotation` created with `cvssScore: 8.6` and `exploitAvailable: true` was updated with `mergeUpdate: true` and only `reproductionSteps` in the properties. Afterwards it held `cvssScore: 0.0` and `exploitAvailable: false`. Egeria cannot tell a primitive that was left out of a merge update from one set to 0 / false, so it stores the default over the current value. So any merge update of a security annotation resets the CVSS score, the exploit and patch flags, and the posture counts it doesn't mention. This raises the question above from "an unset value reads as 0" to "an update loses data". **pyegeria workaround (step 4 PR):** Dr.Egeria's `SecurityFindingProcessor` copies those fields' current values into every merge update unless the command sets them (verified live: the same update then kept 8.6 / true). Callers of `DataDiscovery.update_annotation` must do the same until Egeria changes.
+
 **pyegeria workaround (PR #495, until then):** the security report rows (`DataDiscovery._security_row`, behind the `Security-Findings`, `Penetration-Test-Findings` and `Security-Posture` report specs) leave a value blank where a 0 or false would read as an answer nobody gave:
 - a CVSS score of 0.0 is shown only when the severity is "None";
 - `exploitAvailable` and `patchAvailable` are shown only when true;

PYEGERIA_ISSUES.md

@@ -1852,6 +1852,8 @@ So "never set" and "set to 0 / false" come back identical. Confirmed live on 202
 
 **Question for the Egeria team (Mandy):** could these become boxed types (`Float`, `Boolean`, `Long`, `Integer`) with a `null` default, so that an unset value is omitted from the response? `cvssScore` matters most: a CVSS score of 0.0 is a real rating (severity "None").
 
+**Addendum 2026-10-26 (later the same day): a merge update wipes these fields.** While live-testing the Dr.Egeria finding commands (step 4), a `PenetrationTestFindingAnnotation` created with `cvssScore: 8.6` and `exploitAvailable: true` was updated with `mergeUpdate: true` and only `reproductionSteps` in the properties. Afterwards it held `cvssScore: 0.0` and `exploitAvailable: false`. Egeria cannot tell a primitive that was left out of a merge update from one set to 0 / false, so it stores the default over the current value. So any merge update of a security annotation resets the CVSS score, the exploit and patch flags, and the posture counts it doesn't mention. This raises the question above from "an unset value reads as 0" to "an update loses data". **pyegeria workaround (step 4 PR):** Dr.Egeria's `SecurityFindingProcessor` copies those fields' current values into every merge update unless the command sets them (verified live: the same update then kept 8.6 / true). Callers of `DataDiscovery.update_annotation` must do the same until Egeria changes.
+
 **pyegeria workaround (PR #495, until then):** the security report rows (`DataDiscovery._security_row`, behind the `Security-Findings`, `Penetration-Test-Findings` and `Security-Posture` report specs) leave a value blank where a 0 or false would read as an answer nobody gave:
 - a CVSS score of 0.0 is shown only when the severity is "None";
 - `exploitAvailable` and `patchAvailable` are shown only when true;

docs/dr_egeria_manual.md

@@ -269,6 +269,7 @@ Dr.Egeria organizes its commands into "families," each corresponding to a specif
 - **Governance Officer**: Manage governance definitions, policies, and responsibilities.
 - **Security Officer** (added 2026-10-26, Egeria 6.3): Statements of applicability — the record of which controls from a standard (such as ISO/IEC 27001 Annex A) apply to the organization, why, and how far each is implemented. Processors in `md_processing/v2/security_officer.py`.
   - `Create`/`Update Statement of Applicability`: an AuthoredReferenceable with `Scope`, `Review Date`, `Authors` and `Content Status` (set APPROVED before an audit). `Certification Standard` links the certification type it is assessed against (GovernedBy); `Scoped By` links the organization, site or system it covers (ScopedBy). Leaving either out leaves its links alone; `Merge Update: false` also removes links the command no longer lists.
+  - Security testing results (model 0665): `Create`/`Update Survey Report` catalogues one test run, through Asset Maker. It takes Category (e.g. Penetration Test Results), Purpose, Start Time and Completion Time; `Report Subjects` links the assets the run tested (ReportSubject). `Create`/`Update Security Finding`, `Vulnerability Finding` and `Penetration Test Finding` each create one finding under its `Survey Report` (ReportedAnnotation, required), with Severity (the CVSS ratings None/Low/Medium/High/Critical), CVSS Score and the type's own fields. `Affected Elements` links catalogued elements (AssociatedAnnotation), `Previous Finding` links the same finding in an earlier run (AnnotationExtension), and `Vulnerability Type` links a reference data value (ReferenceValueAssignment). `Create Security Posture Summary` records a run's counts: `Finding Counts By Severity` takes one `severity: count` pair per line. Egeria stores the CVSS score, exploit/patch flags and posture counts as primitives, so a merge update that leaves one out would reset it to 0 / false; these commands copy the current value into the update to prevent that (ISSUE-166). Processors in `md_processing/v2/security_officer.py`.
   - `Link`/`Unlink Control Applicability`: assess a control (any governance definition, typically a GovernanceControl) in a statement — `Is Applicable`, `Justification`, `Inclusion Reasons`, `Implementation Status` (NOT_STARTED, PLANNED, PARTIALLY_IMPLEMENTED, IMPLEMENTED, OTHER), `Implementation Description`, `Review Date`, and `Label` for the control's number in the standard. There is one relationship per control, and re-running Link updates it. Egeria's attach replaces the relationship's properties wholesale, so the command starts from the existing ones: re-linking with just a new status keeps the justification and the rest (`Merge Update: false` replaces them).
   - Reports: `Statement-of-Applicability-Controls` (one row per control — use `LIST` for a markdown table, `DICT` for a spreadsheet) and `Statement-of-Applicability-Implementation-Summary` (applicable controls counted by implementation status; `BAR`/`PIE` for a chart). Both take `soa_guid`, which accepts the statement's GUID or qualified name, e.g. `View Report` with `Report Parameters` `soa_guid: StatementOfApplicability::Coco Pharmaceuticals ISMS`. The summary is analytic-function-backed, which `View Report` cannot run yet; use it through `exec_report_spec` or `SecurityOfficer.get_control_implementation_summary`.
   - Security testing results (Egeria 6.3, model 0665): each test run is a `SurveyReport`, with one `SecurityFindingAnnotation` (or `VulnerabilityAnnotation` / `PenetrationTestFindingAnnotation`) per finding and a `SecurityPostureAnnotation` summarizing the run. The report specs `Security-Findings` (most severe first; params `report_guid` or `element_guid`, each a GUID or qualified name, and optional `min_severity`), `Penetration-Test-Findings` and `Security-Posture` (one row per run, oldest first; optional `report_qualified_name_prefix` to follow one system's series) run through `View Report`. Egeria returns `cvssScore`, `exploitAvailable`, `patchAvailable` and the posture counts as 0 or false when they were never set, so these reports show such values blank rather than as an answer; new and resolved finding counts of 0 cannot be told apart from unrecorded. Dr.Egeria commands for creating survey reports and findings are not available yet.

md_processing/data/compact_commands/commands_curation_compact.json

@@ -2900,7 +2900,7 @@
       "default_value": "",
       "valid_values": [],
       "existing_element": "",
-      "description": "Date/time (ISO 8601) that work started on delivering the promised resource.",
+      "description": "Date/time (ISO 8601) that the work started - for a promise, work on delivering the promised resource; for a report, the run that produced it.",
       "generated": false,
       "style": "Simple",
       "user_specified": true,
@@ -2938,7 +2938,7 @@
       "default_value": "",
       "valid_values": [],
       "existing_element": "",
-      "description": "Date/time (ISO 8601) that the promised resource was delivered.",
+      "description": "Date/time (ISO 8601) that the work finished - for a promise, when the promised resource was delivered; for a report, when the run completed.",
       "generated": false,
       "style": "Simple",
       "user_specified": true,