Implement milestone 9 vulnerability lifecycle and exception governance

Author: Ibraheem Olasupo

.github/workflows/vulnerability-management.yml

@@ -0,0 +1,42 @@
+name: Vulnerability Lifecycle
+
+on:
+  pull_request:
+    branches: ["main"]
+  push:
+    branches: ["main"]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: vulnerability-lifecycle-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lifecycle:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      # actions/checkout v4.2.2
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+
+      # actions/setup-python v5.6.0
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
+        with:
+          python-version: "3.11"
+          cache: "pip"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip==25.1.1
+          python -m pip install -e ".[dev]"
+
+      - name: Source evidence verification
+        run: make verify-findings-evidence verify-release-evidence
+
+      - name: Lifecycle governance tests
+        run: pytest tests/security/test_lifecycle_governance.py -q
+
+      - name: Vulnerability lifecycle
+        run: make lifecycle-full

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing
 
-This portfolio repository is a local demonstration of a secure product foundation. Contributions should preserve the delivered milestone boundaries and avoid adding cloud deployment, formal exception workflow or vulnerability-management operations before their roadmap milestone.
+This portfolio repository is a local demonstration of a secure product foundation. Contributions should preserve the delivered milestone boundaries and avoid adding cloud deployment, production vulnerability-management operations or Security Champions workflow before their roadmap milestone.
 
 ## Local Checks
 
@@ -12,6 +12,7 @@ make appsec-fast
 make dynamic-fast
 make findings-full
 make release-full
+make lifecycle-full
 ```
 
 Use deterministic synthetic data only. Do not add real patient, NHS, genomic, credential, or cloud account data.
@@ -27,3 +28,4 @@ Use deterministic synthetic data only. Do not add real patient, NHS, genomic, cr
 - Do not add broad scanner suppressions. Use `security/config/suppressions.yaml` with an owner, expiry and exact path or rule scope.
 - Keep findings IDs deterministic and avoid absolute local paths, raw JWTs, private keys or real data in canonical findings outputs.
 - Keep release-gate evidence deterministic. Use `make release-gate-enforce` only when you intentionally want enforcement exit codes; evidence-mode release targets must still run for block and conditional decisions.
+- Keep lifecycle evidence deterministic. Scanner suppressions may inform lifecycle records, but only security exceptions under `config/lifecycle/` and `outputs/security/lifecycle/` may support risk acceptance or deferral.

Makefile

@@ -1,4 +1,4 @@
-.PHONY: setup install format format-check lint type-check test test-coverage auth-test api-security-test terraform-fmt terraform-fmt-check terraform-init terraform-validate terraform-test infrastructure-test infrastructure-evidence verify-infrastructure-evidence infrastructure-report security-tools secrets-scan sast sast-semgrep sast-bandit semgrep-test sca dependency-audit sbom verify-sbom iac-scan checkov-scan container-build-security container-scan appsec-fast appsec-full appsec-evidence verify-appsec-evidence appsec-report dynamic-tools dynamic-server-start dynamic-server-wait dynamic-server-stop schemathesis-test api-schema-security-test zap-baseline zap-api-scan auth-boundary-test authorisation-boundary-test object-access-test input-mutation-test security-header-test cors-test resource-consumption-test audit-dynamic-test dast dynamic-evidence verify-dynamic-evidence dynamic-report dynamic-fast dynamic-full findings-normalise findings-deduplicate findings-enrich findings-validate findings-evidence verify-findings-evidence findings-report findings-full release-policy-validate release-gate-evaluate release-gate-enforce release-evidence verify-release-evidence release-report release-full pre-commit-install pre-commit-run quality run docker-build docker-run threat-model-validate threat-model-evidence verify-threat-model-evidence threat-model-report api-security-evidence verify-api-security-evidence api-security-report dev-token-researcher dev-token-approver dev-token-auditor clean
+.PHONY: setup install format format-check lint type-check test test-coverage auth-test api-security-test terraform-fmt terraform-fmt-check terraform-init terraform-validate terraform-test infrastructure-test infrastructure-evidence verify-infrastructure-evidence infrastructure-report security-tools secrets-scan sast sast-semgrep sast-bandit semgrep-test sca dependency-audit sbom verify-sbom iac-scan checkov-scan container-build-security container-scan appsec-fast appsec-full appsec-evidence verify-appsec-evidence appsec-report dynamic-tools dynamic-server-start dynamic-server-wait dynamic-server-stop schemathesis-test api-schema-security-test zap-baseline zap-api-scan auth-boundary-test authorisation-boundary-test object-access-test input-mutation-test security-header-test cors-test resource-consumption-test audit-dynamic-test dast dynamic-evidence verify-dynamic-evidence dynamic-report dynamic-fast dynamic-full findings-normalise findings-deduplicate findings-enrich findings-validate findings-evidence verify-findings-evidence findings-report findings-full release-policy-validate release-gate-evaluate release-gate-enforce release-evidence verify-release-evidence release-report release-full lifecycle-policy-validate lifecycle-initialise lifecycle-validate lifecycle-expiry lifecycle-evidence verify-lifecycle-evidence lifecycle-report lifecycle-full pre-commit-install pre-commit-run quality run docker-build docker-run threat-model-validate threat-model-evidence verify-threat-model-evidence threat-model-report api-security-evidence verify-api-security-evidence api-security-report dev-token-researcher dev-token-approver dev-token-auditor clean
 
 PYTHON ?= python3
 VENV ?= .venv
@@ -228,6 +228,29 @@ release-report:
 release-full:
 	PYTHONPATH=src $(PYTHON) -m genomic_research_access_api.security.release full --timestamp 2026-01-01T00:00:00Z --as-of-date 2026-01-01 --environment dev
 
+lifecycle-policy-validate:
+	PYTHONPATH=src $(PYTHON) -m genomic_research_access_api.security.lifecycle validate
+
+lifecycle-initialise:
+	PYTHONPATH=src $(PYTHON) -m genomic_research_access_api.security.lifecycle initialise --timestamp 2026-01-01T00:00:00Z --as-of-date 2026-01-01
+
+lifecycle-validate:
+	PYTHONPATH=src $(PYTHON) -m genomic_research_access_api.security.lifecycle initialise --timestamp 2026-01-01T00:00:00Z --as-of-date 2026-01-01
+
+lifecycle-expiry:
+	PYTHONPATH=src $(PYTHON) -m genomic_research_access_api.security.lifecycle evaluate-expiry --timestamp 2026-01-01T00:00:00Z --as-of-date 2026-01-01
+
+lifecycle-evidence:
+	PYTHONPATH=src $(PYTHON) -m genomic_research_access_api.security.lifecycle generate-evidence --timestamp 2026-01-01T00:00:00Z --as-of-date 2026-01-01
+
+verify-lifecycle-evidence:
+	PYTHONPATH=src $(PYTHON) -m genomic_research_access_api.security.lifecycle verify-evidence
+
+lifecycle-report:
+	PYTHONPATH=src $(PYTHON) -m genomic_research_access_api.security.lifecycle generate-reports
+
+lifecycle-full: verify-findings-evidence verify-release-evidence lifecycle-policy-validate lifecycle-initialise lifecycle-expiry lifecycle-validate lifecycle-evidence verify-lifecycle-evidence lifecycle-report
+
 pre-commit-install:
 	$(PYTHON) -m pip install pre-commit==3.8.0
 	$(VENV)/bin/pre-commit install

README.md

@@ -8,7 +8,7 @@ It is not a production genomics platform.
 
 It is not affiliated with or endorsed by Genomics England.
 
-AWS infrastructure is provided as non-deployed Terraform. External identity-provider integration, cloud deployment, formal exception workflow and vulnerability-management operations are deferred to later milestones.
+AWS infrastructure is provided as non-deployed Terraform. External identity-provider integration, cloud deployment and Security Champions operations are deferred to later milestones.
 
 ## Problem Statement
 
@@ -32,6 +32,8 @@ Milestone 7 adds canonical findings normalisation and risk enrichment across thr
 
 Milestone 8 adds risk-based release gates over the Milestone 7 canonical findings. It produces deterministic release decisions, rule evaluations, approval requirements, action lists, risk summaries and reports. Evidence generation succeeds for blocked and conditional decisions; enforcement is a separate command. It does not deploy, push containers, create AWS resources, or implement a formal exception workflow.
 
+Milestone 9 adds deterministic vulnerability lifecycle and exception governance over canonical findings and release outputs. It produces a vulnerability register, lifecycle history, security exception register, expiry reports, verification evidence, audit reports and a pinned lifecycle workflow. It does not start Security Champions, deploy, push containers, create AWS resources, commit or push.
+
 ## Milestone 1 Scope
 
 Implemented:
@@ -125,6 +127,22 @@ Implemented as local release-assurance policy and evidence:
 
 Not implemented in Milestone 8: formal exception workflow, deployment approval system, vulnerability lifecycle ownership process, artefact signing/provenance, AWS deployment, container push or production release automation.
 
+## Milestone 9 Scope
+
+Implemented as local governance, evidence and reports:
+
+- Controlled vulnerability lifecycle states and transition policy.
+- Deterministic vulnerability register generated from canonical findings.
+- Role-based history entries without personal actor identifiers.
+- Verification-before-closure enforcement.
+- False-positive governance with rationale and evidence.
+- Formal time-bound security exceptions for risk acceptance and deferral.
+- Exception expiry, expiring-soon and expired-exception outputs.
+- Lifecycle evidence manifest with deterministic checksums.
+- Lifecycle Markdown reports and a pinned CI workflow.
+
+Not implemented in Milestone 9: Security Champions, production ticketing integration, deployment approvals, artefact signing/provenance, AWS deployment, container push or production vulnerability-management operations.
+
 ## API Capabilities
 
 - `GET /health`
@@ -204,6 +222,14 @@ Open `http://127.0.0.1:8000/docs` for FastAPI's local OpenAPI UI.
 - `make release-report`: generate release-assurance Markdown reports.
 - `make release-full`: generate, verify and report release-assurance evidence.
 - `make release-gate-enforce`: enforce the current release decision and return nonzero for block or missing conditional approvals.
+- `make lifecycle-policy-validate`: validate lifecycle, transition, verification, exception, ownership and role policy.
+- `make lifecycle-initialise`: initialise the vulnerability register from canonical findings.
+- `make lifecycle-validate`: validate lifecycle records and exception references.
+- `make lifecycle-expiry`: evaluate exception expiry and lifecycle reactivation state.
+- `make lifecycle-evidence`: generate deterministic lifecycle evidence.
+- `make verify-lifecycle-evidence`: verify lifecycle evidence checksums and determinism.
+- `make lifecycle-report`: generate lifecycle governance reports.
+- `make lifecycle-full`: verify findings and release evidence, then run the full lifecycle workflow.
 - `make secrets-scan`: run Gitleaks via local binary or pinned container.
 - `make semgrep-test`: run Semgrep custom rule tests.
 - `make sast`: run Semgrep and Bandit.

SECURITY.md

@@ -6,7 +6,7 @@ If you identify a vulnerability or unsafe pattern in this demonstration code, op
 
 Do not submit real patient data, NHS data, genomic data, credentials, cloud account identifiers, or sensitive operational details in reports.
 
-Current implemented security controls include local JWT authentication, role-based and object-level authorisation, threat-model validation, non-deployed Terraform reference controls, a Milestone 5 AppSec pipeline, Milestone 6 local dynamic API security validation, Milestone 7 canonical findings normalisation, and Milestone 8 local release-assurance gates.
+Current implemented security controls include local JWT authentication, role-based and object-level authorisation, threat-model validation, non-deployed Terraform reference controls, a Milestone 5 AppSec pipeline, Milestone 6 local dynamic API security validation, Milestone 7 canonical findings normalisation, Milestone 8 local release-assurance gates, and Milestone 9 vulnerability lifecycle and exception governance.
 
 Run local security checks with:
 
@@ -16,6 +16,7 @@ make appsec-fast
 make dynamic-fast
 make findings-full
 make release-full
+make lifecycle-full
 ```
 
-Docker-backed Gitleaks, Trivy, Schemathesis and ZAP scans require a running Docker daemon when native binaries or scanner containers are used. Dynamic scan targets must remain local-only. Do not treat local scanner, findings or release evidence as a production vulnerability-management programme, penetration test, formal exception workflow or deployment approval system.
+Docker-backed Gitleaks, Trivy, Schemathesis and ZAP scans require a running Docker daemon when native binaries or scanner containers are used. Dynamic scan targets must remain local-only. Do not treat local scanner, findings, release or lifecycle evidence as a production vulnerability-management programme, penetration test, deployment approval system or Security Champions programme.

config/lifecycle/actor-roles.yaml

@@ -0,0 +1,12 @@
+{
+  "schema_version": "1.0",
+  "roles": [
+    "Product Security",
+    "Application Engineering",
+    "Platform Engineering",
+    "Cloud Security",
+    "Technical Owner",
+    "Risk Owner",
+    "Verifier"
+  ]
+}

config/lifecycle/exception-policy.yaml

@@ -0,0 +1,23 @@
+{
+  "schema_version": "1.0",
+  "maximum_duration_days": {
+    "critical": 14,
+    "high": 30,
+    "medium": 90,
+    "low": 180,
+    "informational": 180,
+    "unknown": 90
+  },
+  "approval_roles": {
+    "critical": ["Product Security", "Risk Owner", "Technical Owner"],
+    "high": ["Product Security", "Risk Owner"],
+    "medium": ["Product Security"],
+    "low": ["Technical Owner"],
+    "informational": ["Technical Owner"],
+    "unknown": ["Product Security"]
+  },
+  "allowed_statuses": ["requested", "under_review", "approved", "rejected", "active", "expired", "revoked", "closed"],
+  "allowed_decisions": ["approve", "reject", "revoke", "extend", "close"],
+  "scope_required": true,
+  "permanent_exceptions_allowed": false
+}

config/lifecycle/fixtures/lifecycle-overrides.yaml

@@ -0,0 +1,33 @@
+{
+  "schema_version": "1.0",
+  "false_positive_selectors": [
+    {
+      "name": "local zap version notice",
+      "source_tool": "zap",
+      "normalised_severity": "low",
+      "false_positive_reason": "Local scanner version notice is retained as source evidence but does not represent an application vulnerability.",
+      "reviewer_role": "Product Security",
+      "supporting_evidence": "outputs/security/dynamic/zap-summary.json"
+    }
+  ],
+  "risk_acceptance_selectors": [
+    {
+      "name": "no-fix runtime base dependency",
+      "source_tool": "trivy",
+      "normalised_severity": "high",
+      "exception_kind": "active"
+    },
+    {
+      "name": "reference infrastructure reviewed exception",
+      "source_tool": "checkov",
+      "normalised_severity": "high",
+      "exception_kind": "expiring"
+    },
+    {
+      "name": "expired reference infrastructure exception",
+      "source_tool": "checkov",
+      "normalised_severity": "high",
+      "exception_kind": "expired"
+    }
+  ]
+}

config/lifecycle/lifecycle-policy.yaml

@@ -0,0 +1,15 @@
+{
+  "schema_version": "1.0",
+  "policy_version": "1.0",
+  "default_initial_status": "triaged",
+  "controlled_timestamp": "2026-01-01T00:00:00Z",
+  "as_of_date": "2026-01-01",
+  "deployment_status": "not_deployed",
+  "due_soon_days": 7,
+  "exception_expiring_soon_days": 14,
+  "limitations": [
+    "Portfolio demonstration policy, not Genomics England policy.",
+    "Lifecycle records are local deterministic evidence, not a production ticketing system.",
+    "Milestone 9 does not implement Security Champions, dashboards, external ticketing or deployment."
+  ]
+}

config/lifecycle/ownership-policy.yaml

@@ -0,0 +1,7 @@
+{
+  "schema_version": "1.0",
+  "required_owner_fields": ["technical_owner", "risk_owner", "remediation_owner", "squad"],
+  "critical_high_require_owner_before": ["assigned", "in_remediation"],
+  "allowed_owners_source": "config/findings/ownership.yaml",
+  "unowned_value": "unowned"
+}