Security annotation models and security findings / posture reports (Egeria 6.3)

docs/dr_egeria_manual.md

@@ -271,6 +271,7 @@ Dr.Egeria organizes its commands into "families," each corresponding to a specif
   - `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.
   - `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.
 - **Action Author**: Define governance action process flows — reusable single-step action types and multi-step processes — and wire them to the engines and elements that execute them, without writing code (e.g., `Create Governance Action Process`, `Create Governance Action Process Step`, `Link First Process Step`, `Link Next Process Step`, `Link Action to Action Executor`, `Link Action to Target`).
 - **Curation**: Apply classifications and relationships to *existing* Referenceable elements after the fact — this family creates no elements of its own, it curates ones created elsewhere. Every command names a `Target Element` (Reference Name) and either a classification level/status or a second element to relate to.
   - **Classifications** (`Classify`/`Reclassify`/`Declassify`, or `Classify`/`Update`/`Declassify` for the three multi-value ones): Impact, Confidence, Confidentiality, Criticality, Retention, Ownership, Digital Resource Origin, Zone Membership, Security Tags, Data Scope, Governance Expectations, Governance Measurements, Known Duplicate, Consolidated Duplicate, and the 0438 naming-standards markers Class Word, Modifier, Prime Word (added 2026-08-09 once Egeria PR #9166 shipped the backing `glossary-manager` endpoints — routed through `GlossaryManager`, not `ClassificationExplorer`, unlike every other classification here). Also, added 2026-08-21 once an `omvs_audit.py` gap-closure pass shipped their backing REST endpoints (all confirmed against a live 6.2-SNAPSHOT server): the 10 governance-point classifications (0435: Control/Verification/Enforcement/Execution Point, Policy Administration/Decision/Enforcement/Information/Management/Retrieval Point — routed through `GovernanceOfficer`), 6 metamodel markers (0463: Incomplete, ObjectIdentifier, ReferenceData, MobileResource, InstanceMetadata, MetamodelInstance — routed through `ClassificationExplorer`), ProjectKind (routed through `ProjectManager`), CollectionKind (routed through `CollectionManager`), and a Data Sharing Agreement retrofit pair for classifying/declassifying an already-existing Agreement (routed through `DigitalBusiness` — `Create Data Sharing Agreement`, Digital Products family, already sets this at creation time via `initialClassifications`). Also Promise (0010, added 2026-09-30 — `Classify`/`Declassify Promise`, routed through `ClassificationExplorer`): marks an element as a placeholder for a real-world resource that has not yet been delivered, with Deployment Status, Start/Due/Last Review/Completion Time and Additional Properties. A promised element is only visible to lineage requests, so `Declassify Promise` looks up its Target Element and sends the clear request with `forLineage=true` automatically.

pyegeria/models/__init__.py

@@ -77,6 +77,12 @@
     AuthoredReferenceableProperties,
     SolutionBlueprintProperties,
     StatementOfApplicabilityProperties,
+    AnnotationProperties,
+    ResourceMeasureAnnotationProperties,
+    SecurityFindingAnnotationProperties,
+    VulnerabilityAnnotationProperties,
+    PenetrationTestFindingAnnotationProperties,
+    SecurityPostureAnnotationProperties,
     ControlApplicabilityProperties,
     ControlImplementationStatus,
     NestedDesignPatternProperties,
@@ -174,6 +180,12 @@
     "AuthoredReferenceableProperties",
     "SolutionBlueprintProperties",
     "StatementOfApplicabilityProperties",
+    "AnnotationProperties",
+    "ResourceMeasureAnnotationProperties",
+    "SecurityFindingAnnotationProperties",
+    "VulnerabilityAnnotationProperties",
+    "PenetrationTestFindingAnnotationProperties",
+    "SecurityPostureAnnotationProperties",
     "ControlApplicabilityProperties",
     "ControlImplementationStatus",
     "NestedDesignPatternProperties",

pyegeria/models/models.py

@@ -223,6 +223,72 @@ class StatementOfApplicabilityProperties(AuthoredReferenceableProperties):
     review_date: datetime | None = None
 
 
+class AnnotationProperties(AuthoredReferenceableProperties):
+    class_: Annotated[Literal["AnnotationProperties"], Field(alias="class")]
+    annotation_type: str | None = None
+    summary: str | None = None
+    sample_size: int | None = None
+    sample_percent: int | None = None
+    sampling_method: str | None = None
+    confidence: int | None = None
+    units: str | None = None
+    absolute_uncertainty: int | None = None
+    relative_uncertainty: int | None = None
+    expression: str | None = None
+    explanation: str | None = None
+    analysis_step: str | None = None
+    json_properties: str | None = None
+    user_defined_content_status: str | None = None
+
+
+class ResourceMeasureAnnotationProperties(AnnotationProperties):
+    class_: Annotated[Literal["ResourceMeasureAnnotationProperties"], Field(alias="class")]
+    resource_properties: dict[str, str] | None = None
+
+
+class SecurityFindingAnnotationProperties(AnnotationProperties):
+    """A security finding (Egeria 6.3, model 0665). Severity uses the CVSS ratings."""
+    class_: Annotated[Literal["SecurityFindingAnnotationProperties"], Field(alias="class")]
+    severity: Literal["None", "Low", "Medium", "High", "Critical"] | None = None
+    cvss_score: float | None = Field(default=None, ge=0.0, le=10.0)
+    cvss_vector: str | None = None
+    vulnerability_identifiers: list[str] | None = None
+    weakness_identifiers: list[str] | None = None
+    affected_location: str | None = None
+    evidence: str | None = None
+    remediation: str | None = None
+    exploit_available: bool | None = None
+
+
+class VulnerabilityAnnotationProperties(SecurityFindingAnnotationProperties):
+    """A known vulnerability in the software a resource uses, typically from a scan."""
+    class_: Annotated[Literal["VulnerabilityAnnotationProperties"], Field(alias="class")]
+    package_url: str | None = Field(default=None, alias="packageURL")
+    installed_version: str | None = None
+    fixed_version: str | None = None
+    patch_available: bool | None = None
+
+
+class PenetrationTestFindingAnnotationProperties(SecurityFindingAnnotationProperties):
+    """A weakness a penetration test was able to exploit."""
+    class_: Annotated[Literal["PenetrationTestFindingAnnotationProperties"], Field(alias="class")]
+    attack_vector: str | None = None
+    attack_techniques: list[str] | None = None
+    privileges_gained: str | None = None
+    compromised_resources: list[str] | None = None
+    reproduction_steps: str | None = None
+
+
+class SecurityPostureAnnotationProperties(ResourceMeasureAnnotationProperties):
+    """The summary of one security test run."""
+    class_: Annotated[Literal["SecurityPostureAnnotationProperties"], Field(alias="class")]
+    finding_counts_by_severity: dict[str, int] | None = None
+    resources_in_scope_count: int | None = None
+    resources_tested_count: int | None = None
+    new_finding_count: int | None = None
+    resolved_finding_count: int | None = None
+
+
 class ControlApplicabilityProperties(PyegeriaModel):
     class_: Annotated[Literal["ControlApplicabilityProperties"], Field(alias="class")]
     # Egeria treats a control as applicable unless this is false.