[dwolfson]

Summary

Step 4 of the security annotations hand-off in odpi/egeria-workspaces#702 (design-docs/HANDOFF_pyegeria_security_annotations.md). It adds Dr.Egeria commands for cataloguing security test runs, all in the Security Officer family.

• Create/Update Survey Report: a SurveyReport asset, created through Asset Maker. Its attributes are Category, Purpose, Start Time and Completion Time. Report Subjects links the assets the run tested, through ReportSubject.
• Create/Update Security Finding, Vulnerability Finding and Penetration Test Finding: one annotation per finding, created under its Survey Report. That attribute is required; the finding is linked with ReportedAnnotation and anchored to the report.
  • Each takes Severity and CVSS fields plus its type's own attributes.
  • Affected Elements links catalogued elements through AssociatedAnnotation.
  • Previous Finding links the same finding in an earlier run through AnnotationExtension.
  • Vulnerability Type links a reference data value through ReferenceValueAssignment.
• Create/Update Security Posture Summary: the run's counts. Finding Counts By Severity takes one severity: count pair per line.
• Relationship sync works like the statement of applicability commands (Dr.Egeria statement of applicability commands and control reports (Egeria 6.3) #493). An attribute left out of the command leaves its links alone; Merge Update: false also removes links the command no longer lists.

Found while testing live

• A merge update wipes primitive fields. Egeria declares cvssScore, exploitAvailable, patchAvailable and the posture counts as Java primitives. A merge update that leaves one out resets it to 0 or false. I confirmed this live: a finding with CVSS 8.6 and an available exploit came back as 0.0 / false after an update that only added reproduction steps. The finding processor now copies the current values of those fields into every merge update unless the command sets them, and I verified live that the same update then keeps 8.6 / true. I've added this to ISSUE-166 in PYEGERIA_ISSUES.md and EGERIA_OPEN_ISSUES.md as an addendum. It moves the issue from "an unset value reads as 0" to "an update loses data". DataDiscovery.update_annotation callers outside Dr.Egeria still need to do the same.
• Severity was validated against the wrong values. Without a type, the severity valid-metadata lookup returns DataQualityRule's values (info, warn, …), so "High" failed. The attribute now scopes the lookup to SecurityFindingAnnotation. Egeria registers nothing for that type, so validation falls back to the CVSS ratings in the spec.
• CVSS score type. It's now sent as a number rather than a string.
• Shared attribute descriptions. Start Time and Completion Time are shared with Curation's Classify Promise, and their descriptions were written only for promises. I broadened both, which is why the two Classify Promise templates change.

Verification

• Ran tests/dr-egeria-command-tests/dr_test_security_findings.md end to end against a quickstart running egeria-platform:latest (2026-10-26). It covers a stand-in system, two penetration test runs, one finding of each type, a posture summary per run, a finding chained to the previous run's finding, and an update. I checked the properties and all five relationship types directly in Egeria. Everything was deleted afterwards, each element was confirmed gone by GUID, and a search for "SecTest" returns nothing.
• validate_compact_specs: 0 errors. Attribute-consumption audit on the family: 0 findings.
• 6 new micro-tests in test_dr_egeria_security_officer.py; the full micro-test suite passes (1518).

Relationship to #495

This PR is independent of #495. It only calls SDK methods that already exist (Asset Maker, Data Discovery, Reference Data), and it doesn't touch the files #495 changes apart from separate sections of docs/dr_egeria_manual.md. Once both are merged, View Report with Security-Findings, Penetration-Test-Findings or Security-Posture shows what these commands record.

🤖 Generated with Claude Code