> ## Documentation Index
> Fetch the complete documentation index at: https://hmis-docs.derrickmugabwa.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Security and incident response

> Protect HMIS infrastructure, credentials, clinical data, administration, and integration endpoints.

Apply least privilege at the server, Dokploy, application, database, integration, and network layers. Treat logs, backups, screenshots, DICOM studies, and interface messages as potentially sensitive clinical data.

## Production security baseline

### Host and Dokploy

* Named SSH accounts with keys; restrict SSH to approved VPN or IP ranges.
* HTTPS for Dokploy and every user-facing service.
* Strong authentication and least-privilege project access in Dokploy.
* Timely security patching and a documented emergency update process.
* Public firewall limited to approved SSH, HTTP, and HTTPS traffic.
* Host disk encryption where supported and encrypted off-site backups.

### Application

* `APP_ENV=production`, `APP_DEBUG=false`, and secure session cookies.
* Preserve `APP_KEY` in the recovery vault.
* Public registration remains disabled.
* Named accounts, administrator 2FA, periodic access reviews, and immediate offboarding.
* Role assignments based on job function and segregation of duties.
* Least-privilege Sanctum tokens with owners, abilities, expiry/review, and rotation records.

### Data and integrations

* Never expose PostgreSQL to the public network.
* Keep OIE administration behind VPN, tunnel, allow-list, or identity-aware access.
* Restrict analyzer, MLLP, ASTM, DICOM, and DICOMweb paths to approved systems.
* Enable production-grade Orthanc authentication and access controls before storing real studies.
* Keep mock services stopped, unrouted, and blocked in production.
* Sanitize channel exports, logs, screenshots, messages, and support bundles.

## Secret handling

| Secret                 | Approved location                                   | Prohibited location         |
| ---------------------- | --------------------------------------------------- | --------------------------- |
| `APP_KEY`              | Dokploy variable and recovery vault                 | Git, docs, chat, tickets    |
| Database passwords     | Dokploy variables and recovery vault                | Compose files, screenshots  |
| OIE keystore passwords | Dokploy variables and recovery vault                | Channel exports, docs       |
| Integration tokens     | Target connector secret configuration and vault     | Logs, screenshots, messages |
| Backup keys            | Host backup secret store and offline recovery vault | Application repository      |

Rotate a secret immediately after exposure. Review dependent services, cached configuration, logs, exports, and backups to determine whether the old value remains usable.

## Incident severity

| Severity | Example                                                                             | Immediate action                                                                                  |
| -------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Critical | Active breach, ransomware, database corruption, widespread clinical outage          | Activate incident command, isolate affected systems, preserve evidence, begin downtime procedures |
| High     | Exposed credential, failed production restore, integration producing unsafe results | Contain affected service, revoke access, stop unsafe workflow, notify owners                      |
| Medium   | Repeated queue failure, storage warning, limited workflow outage                    | Assign owner, use workaround, correct within agreed window                                        |
| Low      | Non-urgent misconfiguration or documentation defect                                 | Record and schedule correction                                                                    |

## Incident response

<Steps>
  <Step title="Declare and assign command">
    Record time, reporter, affected environment, known impact, incident commander, clinical lead, technical lead, communications owner, and evidence custodian.
  </Step>

  <Step title="Protect patients and contain">
    Stop unsafe clinical or integration processing, activate downtime procedures, isolate affected accounts/services/networks, and revoke exposed tokens without destroying evidence.
  </Step>

  <Step title="Preserve evidence">
    Retain relevant deployment identifiers, logs, alerts, access events, hashes, timestamps, and system state. Limit PHI access and record who handled evidence.
  </Step>

  <Step title="Eradicate and recover">
    Correct the cause, rotate secrets, rebuild from trusted artifacts when needed, restore through the tested runbook, and reconcile all downtime and external-system records.
  </Step>

  <Step title="Validate and reopen">
    Obtain technical, security, and clinical approval after health, data-integrity, access, workflow, backup, and monitoring checks pass.
  </Step>

  <Step title="Review">
    Document root cause, timeline, impact, decisions, corrective controls, owners, and due dates. Update the relevant runbook without including sensitive incident details.
  </Step>
</Steps>

<Warning>
  Do not delete logs, rotate evidence away, rebuild the server, or restore over the affected environment until the incident commander and evidence owner approve the action.
</Warning>