Implement milestone 13 Repository 5 integration contract

Author: Ibraheem Olasupo

.github/workflows/integration-contract.yml

@@ -0,0 +1,64 @@
+name: integration-contract
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: integration-contract-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  integration-contract:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip==25.1.1
+          python -m pip install -e ".[dev]"
+
+      - name: Verify source evidence
+        run: |
+          make verify-findings-evidence
+          make verify-release-evidence
+          make verify-lifecycle-evidence
+          make verify-consolidated-evidence
+          make verify-champions-evidence
+
+      - name: Validate integration contract
+        run: |
+          make integration-policy-validate
+          make integration-export
+          make integration-validate
+          make verify-integration-evidence
+
+      - name: Run integration tests
+        run: |
+          PYTHONPATH=src pytest tests/security/test_integration_contract.py -q
+
+      - name: Sample consumer validation
+        run: |
+          python examples/integration-consumer/validate_bundle.py outputs/security/integration
+
+      - name: Generate reports
+        run: make integration-report
+
+      - name: Upload export bundle
+        uses: actions/upload-artifact@v4
+        with:
+          name: product-security-export-bundle
+          path: outputs/security/integration/
+          retention-days: 14

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, production vulnerability-management operations beyond the local evidence model, or Repository 5 integration 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 beyond the local evidence model, or live Repository 5 ingestion.
 
 ## Local Checks
 
@@ -16,6 +16,7 @@ make lifecycle-full
 make evidence-full
 make developer-enablement-full
 make champions-full
+make integration-full
 ```
 
 Use deterministic synthetic data only. Do not add real patient, NHS, genomic, credential, or cloud account data.
@@ -38,6 +39,7 @@ Use deterministic synthetic data only. Do not add real patient, NHS, genomic, cr
 - Run `make security-doctor` when Docker, Terraform, Gitleaks, Trivy, ZAP or local dynamic checks fail locally.
 - Keep scanner suppressions narrow, owned and expiring. Use formal lifecycle exceptions only for time-bound accepted risk or deferral with rationale and approval.
 - Regenerate findings, release, lifecycle, consolidated evidence and developer enablement evidence when the corresponding source material changes.
-- Commits should preserve milestone boundaries. Do not add deployment, AWS execution, dashboards, external ticketing or Repository 5 integration before their roadmap milestone.
+- Regenerate integration evidence with `make integration-full` when finding, release, lifecycle, consolidated evidence or integration mapping config changes.
+- Commits should preserve milestone boundaries. Do not add deployment, AWS execution, dashboards, external ticketing or live Repository 5 ingestion.
 
 Run `make champions-full` when changing the Security Champions programme, roster, metrics, maturity model, escalation policy, workshops, exercises or reports. Champion records must remain synthetic and role-based.

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 lifecycle-policy-validate lifecycle-initialise lifecycle-validate lifecycle-expiry lifecycle-evidence verify-lifecycle-evidence lifecycle-report lifecycle-full evidence-source-validate evidence-aggregate evidence-generate verify-consolidated-evidence evidence-report evidence-full security-assurance-full security-doctor developer-docs-validate developer-enablement-evidence verify-developer-enablement-evidence developer-enablement-report developer-enablement-full champions-policy-validate champions-metrics champions-evidence verify-champions-evidence champions-report champions-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 evidence-source-validate evidence-aggregate evidence-generate verify-consolidated-evidence evidence-report evidence-full integration-policy-validate integration-export integration-validate verify-integration-evidence integration-report integration-full security-assurance-full security-doctor developer-docs-validate developer-enablement-evidence verify-developer-enablement-evidence developer-enablement-report developer-enablement-full champions-policy-validate champions-metrics champions-evidence verify-champions-evidence champions-report champions-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
@@ -268,7 +268,24 @@ evidence-report:
 
 evidence-full: verify-threat-model-evidence verify-api-security-evidence verify-infrastructure-evidence verify-appsec-evidence verify-dynamic-evidence verify-findings-evidence verify-release-evidence verify-lifecycle-evidence evidence-source-validate evidence-generate verify-consolidated-evidence evidence-report
 
-security-assurance-full: quality verify-threat-model-evidence verify-api-security-evidence verify-infrastructure-evidence verify-appsec-evidence verify-dynamic-evidence findings-full release-full lifecycle-full developer-enablement-full champions-full evidence-full
+integration-policy-validate:
+	PYTHONPATH=src $(PYTHON) -m genomic_research_access_api.security.integration validate-policy
+
+integration-export:
+	PYTHONPATH=src $(PYTHON) -m genomic_research_access_api.security.integration export --timestamp 2026-01-01T00:00:00Z --as-of-date 2026-01-01
+
+integration-validate:
+	PYTHONPATH=src $(PYTHON) -m genomic_research_access_api.security.integration validate-export
+
+verify-integration-evidence:
+	PYTHONPATH=src $(PYTHON) -m genomic_research_access_api.security.integration verify
+
+integration-report:
+	PYTHONPATH=src $(PYTHON) -m genomic_research_access_api.security.integration report
+
+integration-full: verify-findings-evidence verify-release-evidence verify-lifecycle-evidence verify-consolidated-evidence integration-policy-validate integration-export integration-validate verify-integration-evidence integration-report
+
+security-assurance-full: quality verify-threat-model-evidence verify-api-security-evidence verify-infrastructure-evidence verify-appsec-evidence verify-dynamic-evidence findings-full release-full lifecycle-full developer-enablement-full champions-full evidence-full integration-full
 
 security-doctor:
 	PYTHONPATH=src $(PYTHON) -m genomic_research_access_api.security.enablement doctor

README.md

@@ -40,6 +40,8 @@ Milestone 11 adds developer security enablement: repository-specific secure deve
 
 Milestone 12 adds a local Security Champions programme: charter, role definition, onboarding, 90-day plan, monthly learning cadence, workshops, exercises, checklists, escalation model, metrics, maturity model, evidence and reports. It uses synthetic role-based records only and does not implement Repository 5 integration, dashboards, ticketing, messaging, deployment or AWS resource creation.
 
+Milestone 13 adds a versioned Repository 5 integration contract. It exports local product-security findings, lifecycle evidence, release-assurance evidence, lineage, ownership and metrics under `outputs/security/integration/` using contract `product-security-control-plane-export` version `1.0`. A consumer control plane can validate the bundle with `examples/integration-consumer/validate_bundle.py`. This milestone does not modify Repository 5, perform live ingestion, deploy, create AWS resources, upload externally, or start Milestone 14.
+
 ## Milestone 1 Scope
 
 Implemented:
@@ -449,14 +451,14 @@ Milestone 3 also implements local signed JWT authentication, RBAC, object-level
 
 Milestone 4 adds secure AWS Terraform configuration for private ECS, least-privilege role separation, encrypted DynamoDB/Secrets/CloudTrail storage, CloudWatch/CloudTrail observability and secure remote-state design. These controls are configured and locally validated, not deployed.
 
-Planned future controls include external IdP integration, production rate limiting, Repository 5 integration and enterprise reporting.
+Planned future controls include external IdP integration, production rate limiting and later enterprise workflows beyond the local Milestone 13 export contract.
 
-This repository does not claim production-grade identity, monitoring, cloud deployment, vulnerability-management workflow or release-gate coverage.
+This repository does not claim production-grade identity, monitoring, cloud deployment, external Repository 5 ingestion, vulnerability-management workflow or release-gate coverage.
 
 ## Limitations
 
-State is in memory and resets when the app restarts. JWT keys under `tests/fixtures/keys/` are synthetic local development material only. Audit retrieval is a local demonstration endpoint restricted by role. Terraform is a non-deployed reference architecture; no AWS resource is created by the repository state. Threat-model risk ratings are qualitative portfolio artefacts, not production risk acceptances.
+State is in memory and resets when the app restarts. JWT keys under `tests/fixtures/keys/` are synthetic local development material only. Audit retrieval is a local demonstration endpoint restricted by role. Terraform is a non-deployed reference architecture; no AWS resource is created by the repository state. Threat-model risk ratings are qualitative portfolio artefacts, not production risk acceptances. The Repository 5 integration contract is a deterministic local export bundle only; no external transfer or consumer ingestion is performed.
 
 ## Future Milestones
 
-Later milestones may add external identity-provider integration, Repository 5 integration and enterprise reporting.
+Later milestones may add external identity-provider integration and enterprise reporting beyond the local export contract.

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, Milestone 8 local release-assurance gates, Milestone 9 vulnerability lifecycle and exception governance, and Milestone 10 consolidated security evidence reporting.
+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, Milestone 9 vulnerability lifecycle and exception governance, Milestone 10 consolidated security evidence reporting, Milestone 11 developer enablement, Milestone 12 Security Champions evidence, and Milestone 13 local Repository 5 integration-contract export evidence.
 
 Run local security checks with:
 
@@ -20,10 +20,11 @@ make lifecycle-full
 make evidence-full
 make developer-enablement-full
 make champions-full
+make integration-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, release, lifecycle, consolidated or Security Champions evidence as a production vulnerability-management programme, penetration test, deployment approval system, regulatory certification or external training system.
 
-Developer guidance is under `docs/developer-security/`. It explains safe reproduction, local-only DAST boundaries, scanner suppressions, formal security exceptions, release gates and evidence expectations. Do not submit real secrets, raw JWTs, private keys, exploit payloads, cloud identifiers or personal contact details in issues, pull requests or evidence.
+Developer guidance is under `docs/developer-security/`. It explains safe reproduction, local-only DAST boundaries, scanner suppressions, formal security exceptions, release gates and evidence expectations. Integration guidance is under `docs/integration/` and covers the local export contract only. Do not submit real secrets, raw JWTs, private keys, exploit payloads, cloud identifiers or personal contact details in issues, pull requests or evidence.
 
 Security Champions guidance is under `security-champions/`. It is a synthetic role-based operating model for facilitation, learning, triage support and escalation. Champions do not replace Product Security accountability or Risk Owner acceptance.

config/evidence/control-mapping.yaml

@@ -9,6 +9,7 @@
     "developer_enablement": ["developer_enablement"],
     "findings": ["governance", "supply_chain"],
     "infrastructure": ["infrastructure_security", "iam", "data_protection", "audit_logging"],
+    "integration": ["integration_contract"],
     "lifecycle": ["vulnerability_management", "governance", "audit"],
     "release_assurance": ["release_assurance"],
     "threat_model": ["secure_design"]

config/integration/compatibility-policy.yaml

@@ -0,0 +1,22 @@
+{
+  "compatibility_statuses": [
+    "compatible",
+    "compatible_with_warnings",
+    "incompatible"
+  ],
+  "minimum_consumer_version": "1.0",
+  "required_manifest_fields": [
+    "contract_name",
+    "contract_version",
+    "producer",
+    "producer_repository",
+    "record_count",
+    "lineage_edge_count",
+    "output_checksums",
+    "compatibility_status",
+    "validation_status"
+  ],
+  "supported_contract_versions": [
+    "1.0"
+  ]
+}

config/integration/control-mapping.yaml

@@ -0,0 +1,11 @@
+{
+  "control_domains": {
+    "integration_contract": [
+      "SR-INTEGRATION-001",
+      "SR-INTEGRATION-002",
+      "SR-INTEGRATION-003",
+      "SR-INTEGRATION-004"
+    ]
+  },
+  "mapping_version": "1.0"
+}

config/integration/field-mapping.yaml

@@ -0,0 +1,19 @@
+{
+  "mapping_version": "1.0",
+  "mappings": {
+    "asset_id": "asset_id",
+    "asset_type": "asset_type",
+    "control_ids": "control_ids",
+    "due_date": "due_date",
+    "exception_id": "exception_id",
+    "export_record_id": "derived from contract version, finding_id and producer repository",
+    "finding_id": "canonical finding_id",
+    "lifecycle_status": "lifecycle vulnerability status",
+    "normalised_severity": "normalised_severity",
+    "producer_status": "local lifecycle or finding status",
+    "consumer_status": "neutral status mapping",
+    "release_impact": "release finding decision contribution",
+    "source_finding_ids": "finding-source-map source_finding_ids",
+    "source_record_hash": "canonical source_record_hash"
+  }
+}

config/integration/integration-policy.yaml

@@ -0,0 +1,17 @@
+{
+  "as_of_date_default": "2026-01-01",
+  "consumer": "enterprise-data-saas-security-control-plane",
+  "contract_name": "product-security-control-plane-export",
+  "contract_version": "1.0",
+  "deployment_status": "not_deployed",
+  "limitations": [
+    "Local export bundle only; no Repository 5 modification or live ingestion occurs.",
+    "No APIs, message queues, cloud resources, dashboards or external transfer are implemented.",
+    "Consumer-side identifiers are not fabricated."
+  ],
+  "minimum_consumer_version": "1.0",
+  "producer": "devsecops-application-security-pipeline",
+  "producer_repository": "devsecops-application-security-pipeline",
+  "producer_schema_version": "1.0",
+  "timestamp_default": "2026-01-01T00:00:00Z"
+}