Scope: This report assesses the Arkhivio Backup Framework as a tool handling electronically protected health information (ePHI) against the HIPAA Security Rule. It covers technical and architectural controls only. Organisational policies, workforce training, risk analyses, and Business Associate Agreements remain the responsibility of the operating organisation. This document does not constitute a legal compliance certification.
Local backend supports distinct admin and operator accounts with independent credentials. AD backend authenticates and identifies individual directory users by their username. The authenticated identity is stored as session["username"] and is available to every request handler.
Implemented. SessionMiddleware in main.py is configured with max_age=_SESSION_TIMEOUT, where _SESSION_TIMEOUT = int(os.environ.get("SESSION_TIMEOUT_SECONDS", "3600")). Default is 1 hour. Set SESSION_TIMEOUT_SECONDS=900 in .env for a HIPAA-strict 15-minute timeout. The session cookie expires client-side and the server rejects replayed cookies past max_age.
Transit: all S3 and MongoDB traffic uses TLS enforced by boto3 and the MongoDB driver. Storage: SSE-KMS with a customer-managed key (CMK) must be enabled on the S3 bucket. For HIPAA, SSE-KMS is strongly preferred over SSE-S3 because the CMK is under your control and its usage is auditable in AWS CloudTrail. This is a bucket-level configuration; no framework code change is needed.
aws s3api put-bucket-encryption --bucket <name> --server-side-encryption-configuration '{"Rules":[{"ApplyServerSideEncryptionByDefault":{"SSEAlgorithm":"aws:kms","KMSMasterKeyID":"<key-arn>"},"BucketKeyEnabled":true}]}'s3:PutObject requests that do not include "s3:x-amz-server-side-encryption": "aws:kms" as a condition. This prevents unencrypted objects from being written even if the framework default were changed.tls=true&tlsCAFile=/path/to/ca.pem to MONGO_OPTIONS in .env. On Atlas, TLS is enforced by default and cannot be disabled.All 6 write endpoints (create/update/delete for jobs and buckets) emit a named audit_* log event that includes the authenticated user and the affected resource. These join the full operation log stream produced by every module. Sample:
All timestamps are UTC ISO-8601. Logs can be forwarded to an immutable log store (S3, CloudWatch Logs, Splunk) via the integrations documented in LOG_INTEGRATION.md. For HIPAA, configure log retention to ≥ 6 years (2,190 days).
CRC32 stored per file in both MongoDB and S3 object metadata provides tamper evidence. The 3-check audit command (audit.py) detects any divergence between the local catalogue and S3. S3 Object Lock (WORM) — configurable on the bucket — prevents deletion or overwrite for a defined retention period, satisfying the destruction-prevention requirement.
Local backend: secrets.compare_digest prevents timing-based credential inference. AD backend: LDAP bind validates the password against the directory server; group membership (memberOf) determines the role. HMAC-signed session cookies prevent session forgery. A bad or missing SESSION_SECRET causes an immediate RuntimeError at import time — the server cannot start in a partially-configured state.
All S3 operations use HTTPS via boto3 (TLS 1.2+ enforced by AWS/Cloudflare endpoints). MongoDB connections support TLS via the URI options. config.py warns at startup if TLS is disabled on a non-local MongoDB URI. Additionally, a bucket policy aws:SecureTransport: true can be applied to reject all plain-HTTP requests at the storage layer.
restore_onlys3.py provides a documented, tested recovery path that requires only S3 credentials — no MongoDB, no framework installation, no database restoration needed. Files are plain objects at human-readable paths, accessible with any S3-compatible tool in an emergency.
The framework is self-hosted Python — no BAA with a vendor is required for the software itself. A BAA must be executed with each cloud provider storing ePHI: AWS (covers S3 and optionally MongoDB Atlas), Cloudflare (R2 BAA available for HIPAA customers), MongoDB Atlas (Atlas BAA available on M10+ clusters). Free-tier Atlas M0 is not HIPAA-eligible.
Actions required before a production deployment handling ePHI under HIPAA.
| # | Action | How resolved | Where | Regulation |
|---|---|---|---|---|
| 1 | Enable SSE-KMS with a customer-managed key on the S3 bucket | EXT | AWS / Cloudflare console | §164.312(a)(2)(iv) |
| 2 | Set SESSION_TIMEOUT_SECONDS in .env (default 3600 s; use 900 s for a stricter 15-minute timeout) |
OPS | .env |
§164.312(a)(2)(iii) |
| 3 | Enable TLS on MongoDB connection (MONGO_OPTIONS=tls=true&tlsCAFile=…) |
OPS | .env |
§164.312(e)(1) |
| 4 | Store BACKUP_SECRET_KEY in a secrets manager, not a flat file. Set SECRETS_PROVIDER in .env to activate one of the 6 built-in integrations. |
OPS | .env / secrets provider |
§164.312(a)(2)(iv) |
| 5 | Enable S3 Object Lock (WORM) on the bucket for the required retention period | EXT | AWS / Cloudflare console | §164.312(c)(1) |
| 6 | Forward log output to an immutable log store (CloudWatch Logs, Splunk, Loki). Set LOG_FILE in .env and configure a log shipper per LOG_INTEGRATION.md. Set retention to ≥ 2,190 days (6 years). |
OPS | .env / log shipper |
§164.312(b) |
| 7 | Execute BAA with AWS, Cloudflare, and/or MongoDB Atlas | EXT | Legal / provider portals | §164.308(b) |
| Capability | How it supports HIPAA |
|---|---|
| Fernet encryption of credentials | A MongoDB breach alone cannot expose S3 data. Encryption key optionally held in 6 external secrets managers (AWS SM, Azure KV, GCP, IBM, Vault, OpenBao), completely off disk. |
| Minimal data in MongoDB | Only metadata (path, size, mtime, CRC32) — no file content ever stored in the catalogue. Reduces ePHI surface to path names, minimising breach impact. |
| Structured JSON logs with UTC timestamps | Machine-parseable, directly ingestible by every major SIEM. Immutable when forwarded. Timestamps are ISO-8601 UTC, satisfying §164.312(b) audit control requirements. |
| Named audit events on all write operations | audit_job_created/updated/deleted and audit_bucket_created/updated/deleted record the actor, resource, and time for every privileged action — required by §164.312(b). |
| Startup fail-fast validation | _validate_config() in auth.py raises RuntimeError before the server starts if SESSION_SECRET, credentials, or AD variables are missing — prevents running in a degraded security state. |
| 3-check integrity audit | On-demand verifiable evidence that ePHI backups are intact and recoverable. JSON output satisfies §164.312(c)(1) integrity and §164.308(a)(7) contingency testing requirements. |
| S3-only disaster recovery | Satisfies §164.312(a)(2)(ii) emergency access requirement. Only S3 credentials needed — no MongoDB, no framework binary during a crisis. |
| HIPAA-annotated session timeout | Source comment at main.py:27 explicitly references §164.312(a)(2)(iii). Default 3,600 s; configurable down to 900 s via SESSION_TIMEOUT_SECONDS for stricter environments. |